Re: HTML node names: Not emitting 'Top (Manual name)'</span></a></span> </h1> <p class="darkgray font13"> <span class="sender pipe"><a href="/search?l=help-texinfo@gnu.org&q=from:%22Patrice+Dumas%22" rel="nofollow"><span itemprop="author" itemscope itemtype="http://schema.org/Person"><span itemprop="name">Patrice Dumas</span></span></a></span> <span class="date"><a href="/search?l=help-texinfo@gnu.org&q=date:20240316" rel="nofollow">Sat, 16 Mar 2024 07:29:45 -0700</a></span> </p> </div> <div itemprop="articleBody" class="msgBody"> <!--X-Body-of-Message--> <pre>On Sat, Mar 16, 2024 at 09:55:59AM +0200, Eli Zaretskii wrote: > Since there's so much material about customizations in the Texinfo > manual, I never paid any attention to the texi2any_api manual (which > is mentioned in the Texinfo manual exactly once, in a place where one > rarely looks). > > Looking at that manual now, it is mainly intended for Perl > programmers, AFAIU.</pre><pre> Not necessarily, some simple customization can be done with almost no knowledge of Perl. Many possibilities for customization require a good knowledge of Perl, though (starting with chapter 6). > Where the effects can be achieved via > customization variables, it basically refers back to the Texinfo > manual. It depends on the section, in some sections the customization variables are well described (for example the section on contents, if I recall well), in other there is only a reference back to the Texinfo manual. > What I was looking for is some kind of combination, in a single > manual, where one could find both the general background and > description of the conversion process (as texi2any_api does), and > description of the customizations via variables in the context of that > description of the conversion process. Customization by writing Perl > function should be considered a whole different level of > customizations, which I believe very few will go to, especially given > the large number of variables which presumably should already allow to > do a lot, and should therefore be described in separate subsections. Ok. The organization of documentation of customization variables in the Texinfo document seems to me a relevant topic for discussion. I'll start a new thread on bug-texinfo on that specific subject. > I indeed note that the first thing the texi2any_api manual says is > this: > > Warning: All of this information, with the exception of > command-line options and search directories associated with command > line options (*note Loading Init Files::), may become obsolete in a > future Texinfo release. Right now, the "API" described in this > chapter is immature, so we must keep open the possibility of > incompatible, possibly major, changes. Of course we try to avoid > incompatible changes, but it is not a promise. > > If still true, this doesn't encourage one, to say the least, to build > serious tailoring on the facilities described in this manual. It is true, the API has not been used that much for now, so it requires a bit of time to be considered as stable. The last of the API was added in 2022-10-29 and it has been changed importantly since then, in particular for the translation of HTML conversion to C. Going forward it should be more stable, but I think that it needs to be used a bit to be sure that it is really ok as it is. The Lilypond manual is now using a relevant part of the API, so let's hope that it can become stable soon. > I hope the plight of a GNU maintainer who needs to tailor or customize > the HTML form of the manual, for whatever reasons, is now evident, as > are the reasons I don't much like the idea of non-trivial changes in > the HTML output in future Texinfo releases. I also hope that making > these customization facilities more stable and better documented will > be an important goal of the future Texinfo development, given the > hoops through which we otherwise need to jump to get our job done. It has been an important goal for a very long time. This was one of the reason why Karl pushed for texi2html to replace makeinfo in C in 2010. In texi2html the inclusion of some kind of customization cannot be dated with certainty, but dates from before 2000 according to my understanding of the very first ChangeLog entry. Progress may be slow, but it has been an important goal for a long time. -- Pat </pre> </div> <div class="msgButtons margintopdouble"> <ul class="overflow"> <li class="msgButtonItems"><a class="button buttonleft " accesskey="p" href="msg03252.html">Previous message</a></li> <li class="msgButtonItems textaligncenter"><a class="button" accesskey="c" href="index.html#03254">View by thread</a></li> <li class="msgButtonItems textaligncenter"><a class="button" accesskey="i" href="maillist.html#03254">View by date</a></li> <li class="msgButtonItems textalignright"><a class="button buttonright buttondisabled" accesskey="n" href="#">Next message</a></li> </ul> </div> <a name="tslice"></a> <div class="tSliceList margintopdouble"> <ul class="icons monospace"> <li><ul> <li class="icons-email"><span class="subject"><a href="msg03245.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Arsen Arsenović</span></li> <li class="icons-email"><span class="subject"><a href="msg03247.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Eli Zaretskii</span></li> <li class="icons-email"><span class="subject"><a href="msg03255.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Patrice Dumas</span></li> </ul></li> <li class="icons-email"><span class="subject"><a href="msg03246.html">Re: HTML <title> node names: Not emitting 'Top (Man...</a></span> <span class="sender italic">Patrice Dumas</span></li> <li><ul> <li class="icons-email"><span class="subject"><a href="msg03248.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Eli Zaretskii</span></li> <li class="icons-email"><span class="subject"><a href="msg03249.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Gavin Smith</span></li> <li class="icons-email"><span class="subject"><a href="msg03251.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Eli Zaretskii</span></li> <li class="icons-email"><span class="subject"><a href="msg03253.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">pertusus</span></li> <li class="icons-email"><span class="subject"><a href="msg03250.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Patrice Dumas</span></li> <li class="icons-email"><span class="subject"><a href="msg03252.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Eli Zaretskii</span></li> <li class="icons-email tSliceCur"><span class="subject">Re: HTML <title> node names: Not emitting 'Top...</span> <span class="sender italic">Patrice Dumas</span></li> </ul> </ul> </ul> </ul> </ul> </ul> </ul> </ul> </div> <div class="overflow msgActions margintopdouble"> <div class="msgReply" > <h2> Reply via email to </h2> <form method="POST" action="/mailto.php"> <input type="hidden" name="subject" value="Re: HTML <title> node names: Not emitting 'Top (Manual name)'"> <input type="hidden" name="msgid" value="ZfWsyHic9xzip4rn@free.fr"> <input type="hidden" name="relpath" value="help-texinfo@gnu.org/msg03254.html"> <input type="submit" value=" Patrice Dumas "> </form> </div> </div> </div> <div class="aside" role="complementary"> <div class="logo"> <a href="/"><img src="/logo.png" width=247 height=88 alt="The Mail Archive"></a> </div> <form class="overflow" action="/search" method="get"> <input type="hidden" name="l" value="help-texinfo@gnu.org"> <label class="hidden" for="q">Search the site</label> <input class="submittext" type="text" id="q" name="q" placeholder="Search help-texinfo"> <input class="submitbutton" name="submit" type="image" src="/submit.png" alt="Submit"> </form> <div class="nav margintop" id="nav" role="navigation"> <ul class="icons font16"> <li class="icons-home"><a href="/">The Mail Archive home</a></li> <li class="icons-list"><a href="/help-texinfo@gnu.org/">help-texinfo - all messages</a></li> <li class="icons-about"><a href="/help-texinfo@gnu.org/info.html">help-texinfo - about the list</a></li> <li class="icons-expand"><a href="/search?l=help-texinfo@gnu.org&q=subject:%22Re%5C%3A+HTML+%3Ctitle%3E+node+names%5C%3A+Not+emitting+%27Top+%5C%28Manual+name%5C%29%27%22&o=newest&f=1" title="e" id="e">Expand</a></li> <li class="icons-prev"><a href="msg03252.html" title="p">Previous message</a></li> <li class="icons-next"><a href="#" title="n">Next message</a></li> </ul> </div> <div class="listlogo margintopdouble"> </div> <div class="margintopdouble"> </div> </div> </div> <div class="footer" role="contentinfo"> <ul> <li><a href="/">The Mail Archive home</a></li> <li><a href="/faq.html#newlist">Add your mailing list</a></li> <li><a href="/faq.html">FAQ</a></li> <li><a href="/faq.html#support">Support</a></li> <li><a href="/faq.html#privacy">Privacy</a></li> <li class="darkgray">ZfWsyHic9xzip4rn@free.fr</li> </ul> </div> </body> </html>