Re: Texinfo 7.0 changed the name of HTML output directory

[Gavin Smith]

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
> 
> This broke cross-manual references in the Emacs manuals as they are
> accessible here:
> 
>    https://www.gnu.org/software/emacs/manual/
> 
> See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=72761.
> 
> For example, if you go to the above URL, click on "Eglot" and select
> the "one web page per node" variant, you end up here:
> 
>   https://www.gnu.org/software/emacs/manual/html_node/eglot/index.html
> 
> 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".

I couldn't quickly find a broken link on the eglot manual you linked
to, but found a broken link via the debbugs link:

https://www.gnu.org/software/emacs/manual/html_node/flymake/

This has a broken link to

https://www.gnu.org/software/emacs/manual/html_node/eglot_html/Eglot-Features.html#Eglot-Features

The "eglot_html" part of this link is incorrect: it should be

https://www.gnu.org/software/emacs/manual/html_node/eglot/Eglot-Features.html#Eglot-Features

I notice that "eglot" is not listed in "htmlxref.cnf" so will be output
with a default.  The HTML source has

<a data-manual="eglot" 
href="../eglot_html/Eglot-Features.html#Eglot-Features">Eglot Features</a>

for the link.  The code in texi2any (in HTML.pm, _external_node_href)
suffixes the manual name with an underscore and the output format ("html")
when generating this hyperlink.

There are actually two different questions:
* What name to use for the output directory
* What name to use in cross-references by default

These could be different.  We could keep the output directory as
"eglot_html" while changing the hyperlink to refer to, simply, "eglot".

This could potentially break some use cases, but I think they would be
rare.  The common case is that the output directory, e.g. "eglot_html",
would be renamed to e.g. "eglot" when installed on a website.   The
purpose of this change was certainly not to change locations of web pages.

Before this change, I believe the manual would have been output in
a directory called "eglot.html" but this was renamed when installed.
For example, the gendocs.sh script from gnulib renames it to "html_node".
You can see that the manuals for Texinfo itself do not have the "html_"
suffix.

I suspect that the online organisation of the Emacs manuals is slightly
different to that of other projects and changing the default to
"../eglot/" instead of "../eglot_html/" would benefit Emacs but few if
any other projects.

A fix that seems easy is just to add eglot to htmlxref.cnf.  I
will do this and upload it to ftp.gnu.org.  If there are other
manuals that are missing entries can you let us know.