Re: removing the HTML Xref Mismatch node

[Eli Zaretskii]

> Date: Fri, 23 Aug 2024 23:01:25 +0200
> From: Patrice Dumas <pertusus@free.fr>
> 
> While we are on the subject of HTML Xref, I think that the "HTML Xref
> Mismatch" node should be removed
> 
>  
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Mismatch.html
> 
> The information is still true, but I do not think that the solution
> proposed is useful in practice as:
> 1) in general both split and non-split manuals are generated
> 2) with htmlxref.cnf the nature of the target manual is known
> 
> I suggest removing the node from the manual, and put the code example
> somewhere else (maybe in tp/TODO).
> 
> Opinions?

I think the situation that node tries to "solve" is basically
insoluble.  I think when producing a manual that references other
manuals, the person who runs texi2any must know the form (mono, node,
etc.) of the referent manual(s).

My problem is that even if I know that, I'm not sure I understand how
to use that information at HTML-generation time, unless all the
referent manuals are split the same as the manual I'm producing (this
is the only situation clearly described in then Texinfo manual, and
the default operation of texi2any).  But what if the referent manuals
use different splitting, let alone if they use splitting different
from one another (e.g., the manual being produced is node-split,
whereas some referent manuals use chapter-splitting, some others
section-splitting, and some mono)?  How can I tell this to texi2any to
have it generate correct references?  It sounds like the only way is
to have a local htmlxref.cnf file that mentions _only_ the actual
splitting of each referent manual?  If this is the way to go, the
Texinfo manual should say that explicitly.  And if even this will not
solve the problem, then IMO a solution should be designed and
implemented.

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?