Re: HTML <title> node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Fri, Mar 15, 2024 at 09:42:28AM +0200, Eli Zaretskii wrote:
> > What we envisionned, instead, was to provide with the HTML customization
> > API to do the kind of modifications you want to do.  I can imagine a
> > number of reasons why this solution is not that attractive for your use
> > case, for instance it does not allow to be compatible with a wide range
> > of makeinfo releases, may not be that stable, is in Perl, and could
> > require important work.  Still, maybe you could consider using that
> > possibility in the future if you face incompatible changes again.
> 
> 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:
https://www.gnu.org/software/texinfo/manual/texi2any_api/

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...

> 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.

-- 
Pat