On Sat, Aug 24, 2024 at 11:48:08AM +0200, Patrice Dumas wrote: > On Fri, Aug 23, 2024 at 11:01:25PM +0200, Patrice Dumas wrote: > > Hello, > > > > 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 > > Here is what I propose. Could you please check the change in the > last paragraphs of HTML Xref Link Basics? Here is that text obtained > after applying the patch: > > Whether the present manual is split or mono is determined by user > option; @command{texi2any} defaults to split, with the > @option{--no-split} option overriding this. > Whether the referent manual is split or mono, however, is another bit > of the external information (@pxref{HTML Xref Configuration}). > > By default, @command{texi2any} uses the same form of the referent manual as > the > present manual. Thus, there can be a mismatch between the format of the > referent manual that the generating software assumes, and the format it's > actually present in. If there is no external information, both mono > and split form should be generated to be sure that the cross-references > work irrespective of the split option. This is something the software > which generated the @emph{referent} manual has to do in advance, it's > not something the software generating the cross-reference in the present > manual can control.
I started trying to edit this but I have to say that I don't agree with the final paragraph here. It is saying that both split and mono forms of a referent manual need to be generated to link to that manual reliably if that manual is not listed in htmlxref.cnf. However, this is not really the case, as without the correct web address in htmlxref.cnf it won't be possible to link to that manual at all. This is only true in rare cases when collections of manuals are installed under the same subdirectory. It is not clear to me what the purpose of the "HTML Xref Link Basics" node is. You would expect a node called "Basics" to explain frequent and recommended usages, not obscure cases. The node says that an HTML link has the form http://HOST/DIR/FILE.html#TARGET This appears to describe HTML links that are generated in HTML files from Texinfo output to other Texinfo manuals. But it then says: The HOST is hardwired to be the local host. This could either be the literal string ‘localhost’, or, according to the rules for HTML links, the ‘http://localhost/’ could be omitted entirely. This needs more explanation: we certainly do not want to say that links generated in HTML output are always to "localhost".
