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

[Patrice Dumas]

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.

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