Re: Texinfo 7.0 changed the name of HTML output directory

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Thu, 22 Aug 2024 21:12:52 +0100
> Cc: bug-texinfo@gnu.org
> 
> On Thu, Aug 22, 2024 at 10:32:41PM +0300, Eli Zaretskii wrote:
> > 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

Yes.  (And this is just an example; there are more such cases I found
in subdirectories of the html_node directory by searching for
"_html/".)

> 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

Right.

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

Sorry, you lost me here.  Emacs doesn't have an htmlxref.cnf file,
AFAICS.  Are you saying that we need to make sure the file distributed
by Texinfo is up-to-date with the structure of the Emacs manuals, and
that this up-to-date file is present on the system where the HTMl
manuals are generated?  That sounds like an unnecessary maintenance
burden, both for us and for you.

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

Can you explain how this could work?  I always thought that these
parts of each URL must reflect the actual directory structure of the
filesystem where the HTML files reside.

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

If the common case is to rename "eglot_html" to "eglot", then why is
the default "eglot_html"?  In my book, defaults should be identical to
what happens in common cases, otherwise we force everyone and their
dog to customize texi2any.  No?  IOW, I'd expect the version of
htmlxref.cnf distributed by Texinfo to be mostly empty, with the
possible exception of G and GS variables, and possibly other such
variables that document the site of each manual, like BINUTILS, EMACS,
etc. -- so that cross-manual references that point to another project
could be correct.  But the "manual information" lines should not be
present in this file for most if not all manuals, AFAUI, if the
defaults are reasonable.

> Before this change, I believe the manual would have been output in
> a directory called "eglot.html" but this was renamed when installed.

Maybe.  I don't see this renaming in any of the scripts involved in
generating and uploading of the Emacs manuals, but maybe I'm missing
something.

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

Please elaborate.  I don't understand how this can be relevant only to
Emacs.  The only thing that is special to Emacs is that it has many
more manuals than other GNU projects, and maybe more cross-manual
references, but other than that, this should be relevant to any
project that has cross-manual references.

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

Thanks, but that is not enough.  Emacs releases are prepared by one of
several people, as their free time allows, and we cannot rely on each
one of them having the latest version of htmlxref.cnf on the system
where they do this.  We will need to have our own solution within the
Emacs repository, so as not to depend on configuration files
distributed by Texinfo.

Are there other ways of customizing this that do not require to modify
this file?  For example, are there perhaps customization variables
specific to a manual that could be tweaked such that they override
what htmlxref.cnf says about the URL subdirectory structure?

Thanks.