Re: Texinfo 7.0 changed the name of HTML output directory

[Gavin Smith]

On Fri, Aug 23, 2024 at 04:32:41PM +0200, Patrice Dumas wrote:
> 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.

I said at the time that it makes little sense to have "_html" in
URLs:

https://lists.gnu.org/archive/html/bug-texinfo/2022-02/msg00004.html

The part of the "HTML Xref specification" mentioned here dates only to
2022 and actually doesn't matter that much as usually htmlxref.cnf will
be used instead.  I don't think we should be encouraging people to put
"_html" in their URLs.  (It's obvious that it's an HTML page if people
are accessing it with a web browser.)  It is not the important part of
this specification as far as I know - it's what is done with node names
that is the important part.

I hope that people didn't feel encouraged to change the web URL
of manuals based on what was written in the "HTML Xref specification".

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

Exactly.  You just need to update the version of htmlxref.cnf, not
the whole version of Texinfo.

See

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html

(info node "(texinfo)HTML Xref Configuration") for where texi2any
looks for htmlxref.cnf files.  Hopefully it is practical for a project
to add a htmlxref.cnf file for building manuals if they need to.

One thing I wondered reading the documentation is whether htmlxref.cnf
would be found if it was located in the same directory as the
Texinfo source file and how this would work with a build system.

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

To say this again another way, a Texinfo website on the web could have any
domain name and directory name in the URL.  The point of the centralised
version of htmlxref.cnf is to allow these manuals to link to each other
correctly.  The number of entries in htmlxref.cnf is not a sign of failure
in any way.  There is no other way of getting inter-manual links to work
other than having some list of web locations of manuals.

The Emacs manuals are exceptional in all occuring under the directory on
the same domain and so the default links between these manuals starting
"../MANUAL/" worked, but this would not usually be the case.

While changing the default output to "../MANUAL_html/" may have broken
some links between the Emacs manuals, in my opinion such default links
being generated is itself a problem that should be fixed with htmlxref.cnf
files.