Hello,
Here is an updated version of the documentation patch, with Eli text.
On Sat, Aug 24, 2024 at 08:26:13AM +0300, Eli Zaretskii wrote:
> > +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}.
>
> I suggest to tell here explicitly that having a local htmlxref.cnf
> file with the correct information is the solution for outdated or
> missing data in the file as distributed by Texinfo.
I did that, but before in the node.
--
Pat
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index cc772d93ad..d88155397b 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17515,7 +17515,19 @@ @node HTML Xref Link Basics
(@pxref{Cross References}), and from @dfn{external information}
(@pxref{HTML Xref Configuration}).
-We now consider each part in turn.
+@c Eli comment on the next paragraph:
+@c This part is unclear, I could not understand what it means and how
+@c that affects me as the user of Texinfo.
+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
@@ -17830,6 +17842,14 @@ @node HTML Xref Configuration
@cindex Cross-reference configuration, for HTML
@cindex Configuration, for HTML cross-manual references
+For other manuals published on the World Wide Web to be able to have
+correct cross-references to your manual, the @var{host} and
+@var{dir} parts of the cross-reference need to be known by Texinfo
+converters when they produce HTML for those other manuals.
+Similarly, for your manual in HTML format to have correct
+cross-references to other manuals, @command{texi2any} needs to know
+how to construct the URLs for other manuals.
+
@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:
@@ -17862,6 +17882,11 @@ @node HTML Xref Configuration
GNU manuals; it is installed in the last of the above directories,
i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}.
+A local @file{htmlxref.cnf} should be used to complete or correct
+the default file from the Texinfo distribution. This could be useful to
+correct outdated data or make sure that cross-references to local files
+are generated for some manuals.
+
The @code{HTMLXREF_MODE} customization variable can be set to modify how the
files are found. For instance, if set to @samp{none}, no external information
is used. @code{HTMLXREF_FILE} sets the file name to something else than
@@ -17939,9 +17964,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}.
