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.
--
Pat
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 71a34c32ae..2556115ef8 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17517,7 +17517,16 @@ @node HTML Xref Link Basics
(@pxref{Cross References}), and from @dfn{external information}
(@pxref{HTML Xref Configuration}).
-We now consider each part in turn.
+The defaults for the @var{host} and @var{dir} correspond with cross-references
+links for a collection of manuals located side by side on a single host. This
+is different from the usual case of HTML manuals published on the World Wide
+Web served from different hosts in directories chosen by the publisher, for
+which the @var{host} and @var{dir} must be specially defined to have working
+cross-references. However this requires external information and is detailed
+later on (@pxref{HTML Xref Configuration}).
+
+We start with the case of manuals all located on the same
+host and consider each part in turn.
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
@@ -17872,6 +17881,12 @@ @node HTML Xref Configuration
@cindex Cross-reference configuration, for HTML
@cindex Configuration, for HTML cross-manual references
+If you want to generate cross-references to HTML manuals published on
+the World Wide Web, the @var{host} and @var{dir} parts of
+the cross-reference need to be known by Texinfo converters to be able
+to generate cross-references. More generally you may want to specify
+the location of other manuals for cross-references.
+
@command{texi2any} reads a file named @file{htmlxref.cnf} to gather
information for cross-references to other manuals in HTML output. It
is looked for in the following directories:
@@ -17976,9 +17991,17 @@ @node HTML Xref Configuration
only when the target manual was created using @option{--node-files};
this is the default for split output.
+Right now, 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}, HTML manuals
+information 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 in the default case. You can get the latest version from
@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
