On Sat, Aug 24, 2024 at 10:53:29AM +0200, Patrice Dumas wrote:
> > In this connection, this text of "HTML Xref Configuration" is
> > completely unclear to me:
> >
> > However, if a manual is not available in that form, anything that is
> > available can be used. Here is the search order for each style:
> >
> > node ⇒ node, section, chapter, mono
> > section ⇒ section, chapter, node, mono
> > chapter ⇒ chapter, section, node, mono
> > mono ⇒ mono, chapter, section, node
> >
> > These section- and chapter-level cross-manual references can succeed
> > only when the target manual was created using ‘--node-files’; this is
> > the default for split output.
> >
> > When is this search performed and by whom? Is it even relevant to the
> > issue of cross-manual references, and if so, how? And what does the
> > last sentence about --node-files want to say?
>
> It is used when generating the manual that links to the target manual,
> and the sentence about --node-files is about what I explained above.
> I'll try to propose changes to clarify this part.
I've committed the following change; hopefully it makes it a bit clearer.
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 17cb637e4c..1f8ac7727e 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17972,13 +17972,16 @@ @node HTML Xref Configuration
@var{urlprefix} gives the host and directory for @var{manual} split
into nodes, sections, or chapters, respectively.
-When available, @command{texi2any} will use the ``corresponding''
-value for cross-references between manuals. That is, when generating
-monolithic output (@option{--no-split}), the @code{mono} URL will be
-used, when generating output that is split by node, the @code{node}
-URL will be used, etc. However, if a manual is not available in that
-form, anything that is available can be used. Here is the search
-order for each style:
+When @command{texi2any} is generating a link to another Texinfo manual,
+it will prefer to use a line for the manual with the same
+splitting option as the current output. That is, when generating
+monolithic output (@option{--no-split}), a @code{mono} URL will be
+preferred; when generating output that is split by node, a @code{node}
+URL will be preferred, etc.
+
+If no information line with the preferred splitting option is present
+for a given manual, then other lines for that manual can be used if
+present. Here is the full search order for each splitting option:
@example
node @result{} node, section, chapter, mono
