branch master updated: * doc/texinfo.texi (HTML Xref Link Basics, HTML Xref Configuration): Edit.

[Gavin D. Smith]

This is an automated email from the git hooks/post-receive script.

gavin pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new c2c158abb7 * doc/texinfo.texi (HTML Xref Link Basics, HTML Xref 
Configuration): Edit.
c2c158abb7 is described below

commit c2c158abb74264efcb2abc2785a14dd82d80a13a
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Tue Oct 1 21:11:24 2024 +0100

    * doc/texinfo.texi (HTML Xref Link Basics, HTML Xref Configuration):
    Edit.
    
    Patch to documentation posted by Patrice, bug-texinfo 2024-08-23 and
    revised by Gavin.
---
 ChangeLog        |  8 ++++++++
 doc/texinfo.texi | 44 ++++++++++++++++++++++++++++++--------------
 2 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 30f0fc8e1e..e4475ba447 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2024-10-01  Gavin Smith <gavinsmith0123@gmail.com>
+
+       * doc/texinfo.texi (HTML Xref Link Basics, HTML Xref Configuration):
+       Edit.
+
+       Patch to documentation posted by Patrice, bug-texinfo 2024-08-23 and
+       revised by Gavin.
+
 2024-10-01  Patrice Dumas  <pertusus@free.fr>
 
        * tp/maintain/generate_convert_data_perl_code.pl: import
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 @@ manual name in the cross-reference command in the 
Texinfo source
 (@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 @@ the directory is @file{./} (or just the empty string), 
and the file is
 
 @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 @@ These section- and chapter-level cross-manual 
references can succeed
 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}.