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.
