Re: Texinfo 7.0 changed the name of HTML output directory

[Gavin Smith]

On Fri, Aug 23, 2024 at 10:17:33PM +0200, Patrice Dumas wrote:
> On Fri, Aug 23, 2024 at 07:58:04PM +0200, Patrice Dumas wrote:
> > I'll try to come up with some proposal.
> 
> Here it is.  I may have been too explicit and redundant.

I've committed a revised version of this.  I've still got to check other
patches that have been posted for this region of the manual and other
emails with feedback but this is all I've had time to do tonight.

diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 1f8ac7727e..838f63af3d 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17542,19 +17542,21 @@ @node HTML Xref Link Basics
 (@pxref{Cross References}), and from @dfn{external information}
 (@pxref{HTML Xref Configuration}).
 
-We now consider each part in turn.
+In the usual case of HTML manuals published on the World Wide Web, in
+order to have working cross-references, external information is required
+to define the values of @var{host} and @var{dir}.  This is detailed later on
+(@pxref{HTML Xref Configuration}).
 
-The @var{host} is hardwired to be the local host.  This could either
-be the literal string @samp{localhost}, or, according to the rules for
-HTML links, the @samp{http://localhost/} could be omitted entirely.
+If no external information is available for a manual, then defaults are
+used for @var{host} and @var{dir} which correspond to cross-reference
+links among a collection of manuals located side-by-side on a single host.
+In this case, @var{host} is hardwired to be the local host.  This could
+either be the literal string @samp{localhost}, or be omitted entirely along
+with @samp{http://}, according to the rules for HTML links.
 
-The @var{dir} and @var{file} parts are more complicated, and depend on
-the relative split/mono nature of both the manual being processed and
-the manual that the cross-reference refers to.  The underlying idea is
-that there is one directory for Texinfo manuals in HTML, and a given
-@var{manual} is either available as a monolithic file
-@file{@var{manual}.html}, or a split subdirectory
-@file{@var{manual}_html/*.html}.  Here are the cases:
+The @var{dir} and @var{file} parts depend both on the relative split/mono
+nature of the manual being processed, and on the manual to which
+the cross-reference refers:
 
 @itemize @bullet
 @item
@@ -17578,8 +17580,13 @@ @node HTML Xref Link Basics
 
 @end itemize
 
-Another rule, that only holds for file names, is that base file names
-are truncated to 245 characters, to allow for an extension to be
+The underlying idea is that there is one directory for Texinfo
+manuals in HTML, and a given @var{manual} is either available as a
+monolithic file @file{@var{manual}.html}, or as a split subdirectory
+@file{@var{manual}_html/*.html}.
+
+Another rule, which only holds for file names, is that base file names
+are truncated to 245 characters to allow for an extension to be
 appended and still comply with the 255-character limit which is common
 to many filesystems.  Although technically this can be changed with the
 @code{BASEFILENAME_LENGTH} customization variable (@pxref{File Names and Links
@@ -17995,9 +18002,18 @@ @node HTML Xref Configuration
 only when the target manual was created using @option{--node-files};
 this is the default for split output.
 
+At present, the @file{htmlxref.cnf} file distributed with GNU Texinfo
+serves as the main resource to locate Texinfo HTML manuals in the World
+Wide Web.  Since it is installed in a location used by @command{texi2any},
+information on HTML manuals found in this file will be used for
+cross-references by default.
+
 If you have additions or corrections to the @file{htmlxref.cnf}
 distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
-usual.  You can get the latest version from
+usual.  If you publish a Texinfo HTML manual on the World Wide Web,
+having an up-to-date location listed in @file{htmlxref.cnf} should ensure that
+all HTML manuals generated by @command{texi2any} use this location for
+cross-references automatically.  You can get the latest version from
 @url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.