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:%22Eli+Zaretskii%22" rel="nofollow"><span itemprop="author" itemscope itemtype="http://schema.org/Person"><span itemprop="name">Eli Zaretskii</span></span></a></span> <span class="date"><a href="/search?l=help-texinfo@gnu.org&q=date:20240316" rel="nofollow">Sat, 16 Mar 2024 00:56:15 -0700</a></span> </p> </div> <div itemprop="articleBody" class="msgBody"> <!--X-Body-of-Message--> <pre>> Date: Sat, 16 Mar 2024 00:12:21 +0100 > From: Patrice Dumas <pertu...@free.fr> > Cc: gavinsmith0...@gmail.com, ar...@aarsen.me, help-texinfo@gnu.org > > On Fri, Mar 15, 2024 at 09:42:28AM +0200, Eli Zaretskii wrote: > > > > I think the main reason this solution is not used is that it is still > > a kind of "black magic" for almost everyone, definitely for me > > personally. The relevant sections of the Texinfo manual are basically > > a very terse man-page style reference of options in alphabetical > > order, without any kind of tutorial or general explanations or > > examples (without which it is hard to even understand some of the > > customization variables unless one is an HTML expert). This is very > > unlike the other sections of the manual, which invariably provide > > detailed background explanations for each group of commands, describe > > the recommended practices, and provide a lot of examples. I write > > Texinfo manuals for 20 years, and still consult the Texinfo manual all > > the time, always finding valuable information in it in the sections > > that describe the Texinfo language and how to use them in a > > well-written manual. > > The information on HTML output customization and on the HTML output > customization API is not mainly in the Texinfo manual, but in the > texi2any Output Customization manual: > <a rel="nofollow" href="https://www.gnu.org/software/texinfo/manual/texi2any_api/">https://www.gnu.org/software/texinfo/manual/texi2any_api/</a> > > This manual describes how the HTML output can be changed with > customization variables (although is not complete in that regard), but > also with use of functions and functions redefinitions (and should be > complete for that matter). I think that it is more in line with the > expected organization of a manual as you describe than the customization > variables sections of the Texinfo manual. That being said, it is > incomplete, a work in progress, probably with poor grammar, and I am > quite unhappy about the overall organization of some parts of the > manual. I never know if it is worth it investing time in that manual > rather than in texi2any, it is not clear to me that it it is useful to > others...</pre><pre> 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. Where the effects can be achieved via customization variables, it basically refers 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. > > With better documentation, it is quite possible that we could consider > > switching most, if not all, of the code in admin.el to using the > > texi2any customization capabilities -- provided again that those > > customization variables can be relied upon to be stable enough, > > without fearing they will be completely redesigned at some future > > time. > > The customization variables and API described in the texi2any Output > Customization manual are not supposed to be stable yet as the API has > been completed recently and may still need to evolve. So we do not > commit to keeping that interface stable. That being said, it is > probably on the way to stability now that the HTML output code has been > also translated to C and that the changes needed for that have been > made. 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. 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. </pre> </div> <div class="msgButtons margintopdouble"> <ul class="overflow"> <li class="msgButtonItems"><a class="button buttonleft " accesskey="p" href="msg03250.html">Previous message</a></li> <li class="msgButtonItems textaligncenter"><a class="button" accesskey="c" href="index.html#03252">View by thread</a></li> <li class="msgButtonItems textaligncenter"><a class="button" accesskey="i" href="maillist.html#03252">View by date</a></li> <li class="msgButtonItems textalignright"><a class="button buttonright " accesskey="n" href="msg03254.html">Next message</a></li> </ul> </div> <a name="tslice"></a> <div class="tSliceList margintopdouble"> <ul class="icons monospace"> <li class="icons-email"><span class="subject"><a href="msg03243.html">Re: HTML <title> node names: Not emitting 'Top (Man...</a></span> <span class="sender italic">Eli Zaretskii</span></li> <li><ul> <li class="icons-email"><span class="subject"><a href="msg03244.html">Re: HTML <title> node names: Not emitting 'Top...</a></span> <span class="sender italic">Gavin Smith</span></li> <li><ul> <li class="icons-email"><span class="subject"><a href="msg03245.html">Re: HTML <title> node names: Not emitting ...</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 ...</a></span> <span class="sender italic">Eli Zaretskii</span></li> </ul></li> <li class="icons-email"><span class="subject"><a href="msg03246.html">Re: HTML <title> node names: Not emitting 'Top...</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 ...</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 ...</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 ...</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 ...</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 ...</a></span> <span class="sender italic">Patrice Dumas</span></li> <li class="icons-email tSliceCur"><span class="subject">Re: HTML <title> node names: Not emitting ...</span> <span class="sender italic">Eli Zaretskii</span></li> <li class="icons-email"><span class="subject"><a href="msg03254.html">Re: HTML <title> node names: Not emitting ...</a></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="86msqy7gq8.fsf@gnu.org"> <input type="hidden" name="relpath" value="help-texinfo@gnu.org/msg03252.html"> <input type="submit" value=" Eli Zaretskii "> </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="msg03250.html" title="p">Previous message</a></li> <li class="icons-next"><a href="msg03254.html" 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">86msqy7gq8.fsf@gnu.org</li> </ul> </div> </body> </html>