Re: Texinfo 7.0 changed the name of HTML output directory

[Patrice Dumas]

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

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.

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

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

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.

>  and the problem is a nuisance to fix if
> the manuals are hosted in VCS repositories, because a typical VCS has
> at best very weak support for renaming files, and at worst simply
> loses all history before the rename.

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

-- 
Pat