Re: Texinfo 7.0 changed the name of HTML output directory

[Eli Zaretskii]

> Date: Fri, 23 Aug 2024 09:47:57 +0200
> From: Patrice Dumas <pertusus@free.fr>
> Cc: bug-texinfo@gnu.org
> 
> On Thu, Aug 22, 2024 at 10:32:41PM +0300, Eli Zaretskii wrote:
> > Texinfo 7.0 changed the name of the directory where texi2any outputs
> > split-HTML files for a manual:
> > 
> >   7.0 (7 November 2022)
> >   * texi2any
> >   [...]
> >    . HTML output:
> >        . use manual_name_html as output directory for split HTML instead of
> >      manual_name or manual_name.html
> 
> 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 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.  And how
does the --output flag affect the cross-references to other manuals?

> > and references to other manuals now fail because the directory
> > structure of Emacs manuals under manual/html_node/ has subdirectories
> > named by the old convention: "manual_name", not "manual_name_html".
> > 
> > Worse, the directory structure of the Emacs manuals is actually a CVS
> > tree, because all the Emacs manuals that are regenerated for each new
> > release of Emacs are checked into CVS in the
> > cvs.savannah.gnu.org:/web/emacs repository, and from there are posted
> > on the GNU documentation site by the FSF infrastructure.  So now we
> > need either to rename all the subdirectories in CVS (and risk losing
> > the VCS history), or write a script that modifies the cross-manual
> > references to omit the "_html" suffix.
> 
> 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?

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

> > This is exactly the kind of backward-incompatible change that should
> > have never been done, because it breaks on-line manuals that are
> > regenerated for new releases,
> 
> 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.  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).

> If --output is used to specify the directory to follow the HTML Xref
> specification, it may not be corrected that way, but I think that using
> --output is always more consistent with also using htmlxref.cnf to
> specify the target location.

Sede above: I don't follow how --output affects cross-references
between manuals in the html_node/ subdirectories.

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