Re: Texinfo 7.0 changed the name of HTML output directory

[Patrice Dumas]

On Fri, Aug 23, 2024 at 03:53:35PM +0300, Eli Zaretskii wrote:
> > For the reference, it was discussed here:
> > https://lists.gnu.org/archive/html/bug-texinfo/2022-02/msg00003.html
> 
> That discussion failed to examine the existing practices, and failed
> to draw the attention of the relevant package maintainers to the fact
> that their practices were different.
> 
> I'm quite sure that you and Gavin are aware of the FSF infrastructure
> that GNU projects use to upload their manuals to the GNU site and the
> fact it uses CVS as its storage, and therefore I'd expect you to look
> there and compare the actual trees with what this change was about to
> do.

We did not do that, however, for the packages that use gendoc.sh or use
the "html" target in Makefile generated by automake, the change of the
default output directory, by itself does not change the trees, because
in both cases -o/--output is used, such that the default directory is
not used to determine the split HTML output directory.

> > We noted at that time that manuals generated by gendoc.sh and automake
> > generated html targets were not affected directly as they used --output,
> > in a way that was already incompatible with the HTML Xref specification.
> > Many GNU projects use gendoc.sh, but not all, in particular big projects
> > tend to use their own systems.  I have not checked, but I guess that non
> > GNU project often use the texi2any defaults.
> 
> I don't think I follow.  A typical GNU project has an "html" target in
> its Makefile, which invokes makeinfo/texi2any, not gendoc.sh.

As said above, if this html target comes from automake, it uses
-o/--output in makeinfo/texi2any invokation, such that the change in
default output directory do not have any effect.

Regarding gendoc.sh, I do not know what is done by package maintainers,
but the fact is that many GNU packages have their HTML manuals obtained
through https://www.gnu.org/manual/manual.html generated by gendoc.sh,
which leads to a typical gendoc generated page like:
 https://www.gnu.org/software/cpio/manual/

It is less the case for 'big' projects (emacs, lilypond, gcc, gnome,
grub...).  And also probably non GNU manuals do not use much gendoc.

>  And how
> does the --output flag affect the cross-references to other manuals?

It does not directly.  But if the directory given to --output does not
follow the HTML Xref specification, which is the case both for gendoc.sh
generated HTML and the automake generated html target, you need to use
htmlxref.cnf to specify the actual split manuals base URLs, unless you
move HTML files afterwards to the HTML Xref specified location.

> > All the changes in the HTML Xref specification directory lead to that
> > kind of unfortunate incompatible change.
> 
> Then why make such changes at all?  What was so bad about the previous
> defaults?

The rational was exposed in the thread aforementionned that I also
summarised below.

> > Here, you can update all the
> > manuals at once, however, even if it is a hassle.  But for links to
> > truely external manuals it is worse, as there is no possibility of
> > changing already generated manuals.  htmlxref.cnf can be used for
> > external manuals, but it needs to be changed two time, before and after
> > the target manual is regenerated with the new HTML Xref specification.
> 
> Exactly.  Which once again tells me this stuff should not be changed,
> not unless there's a very significant problem with the existing
> defaults.

There was.

> > Here it depends.  If all the manuals are generated using the same HTML
> > Xref specification, it should be ok -- though is still may require
> > change in the build/VCS/... as you report.
> 
> You cannot rely on everybody using the latest version of Texinfo.
> This is impractical and unreasonable.

This is not needed, what is needed is much less stringent.  First it is
only for pairs of manuals for which the target manual do not use
htmlxref.cnf.  Then for such a pair of manual, what matters is the HTML
Xref specification of the Texinfo release, not the Texinfo release.  The
HTML Xref specification changes much more slowly than the Texinfo
release.  In practice, the specification has changed in the 4.7 release,
when it was designed, and in 7.0 release (it changed in 7.1 too, but for
@sc and @point only).  That is not a dramatic requirement.  One could
even consider that this is the type of change to expect for first digit
change release.

>  For example, I'm using one of
> the GNU servers to produce Emacs releases and Emacs manuals to go with
> them, but I'm not the sysadmin of that server, so I cannot always make
> sure I have the latest Texinfo (nor do I always want to have it: for
> example, a bugfix release had better used the same Texinfo version as
> the original one, to avoid introducing new issues).

Of course, this can happen, it is not always possible nor practical to
coordinate on a HTML Xref specification to use for all the manuals with
cross-references to each other, however it also should not be too
difficult when such a discrepancy is detected to ask the other manual in
a pair to use the first Texinfo release with the change in HTML Xref
specification.  It is only for manuals on the same host that this
could happen, if on different hosts one has to use htmlxref.cnf anyway.
(If the htmlxref.cnf entry was based on the HTML Xref specification
there could still be a need to change htmlxref.cnf and redo the manual,
but in practice not many manuals in htmlxref.cnf follow the HTML Xref
specification).

> > > I guess it's too late to lobby for reverting that change?
> > 
> > Indeed.  It could have been reverted before the published change in HTML
> > Xref, but now it is too late.  Also, the previous way lead either to a
> > weird result (with .html) or made HTML output special for no reason.
> > 
> > Overall, we try to avoid making changes in the HTML Xref specification
> > and it does not change that often, but from time to time it still needs
> > to change.
> 
> As I wrote earlier, the fact that htmlxref.cnf has so many entries for
> individual manuals is for me a telltale sign that the new default is
> problematic at best.

The entries in htmlxref.cnf are not related to the change in default
split HTML manual name and most if not all were added before that change.
Having an entry in htmlxref.cnf is needed as soon as a manual has
different splitting (not only by node), or a target manual is not on the
same host.

The change in defaults could lead to htmlxref.cnf entries becoming
incorrect, though.  I do not know if it has been the case.

-- 
Pat