Re: removing the HTML Xref Mismatch node

[Patrice Dumas]

On Sat, Aug 24, 2024 at 08:43:49AM +0300, Eli Zaretskii wrote:
> > 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).

The above mentionned trick could have allowed for the creator of a split
manual to redirect mono references to split files.  That way, when
another manual links to that manual with links assuming a mono
manual they would still find the split manual.  This would lift the
necessity to know the form of the referent manual, but this is not
relevant in practice as, as you noted below, in general, the form is
known in htmlxref.cnf.

> 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.

For mono versus non-mono, having a local htmlxref.cnf file that mentions
_only_ the actual splitting of each referent manual is indeed the only
way to get correct cross-references.  The different split possibilities
(node, section, chapter), however, should be equivalent.  Indeed, if a
split manual is created using ‘--node-files’, targets files for each
node redirecting to the real file are generated for each node even if
the manual is split by section or by chapter.

> 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.

-- 
Pat