Re: Texinfo 7.0 changed the name of HTML output directory

[Eli Zaretskii]

> Date: Sun, 25 Aug 2024 10:54:31 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: bug-texinfo@gnu.org
> 
> > It should be possible to use an additional project-specific htmlxref.cnf
> > file that would take priority.  See 
> > <https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html>.
> 
> This section of the Texinfo manual seems to imply that if a project
> has its own htmlxref.cnf file, that file must be present in every
> directory where HTML manuals are generated.  IOW, there's no way of
> sharing the same file between different subdirectories of the same
> project tree.  Is that conclusion correct?
> 
> Emacs has its manuals in 4 subdirectories of the doc/ directory (and a
> 5th subdirectory, with translations of the manuals, is in the works).
> Since potentially each one of these manuals can cross-reference to
> each one of the other Emacs manuals, and since the HTML versions of
> the manuals are produced by running 'makeinfo' in the corresponding
> subdirectory, AFAIU we need to have the up-to-date cross-reference
> information in each of these 4 subdirectories.  Is that correct?
> 
> There is the HTMLXREF_FILE variable we could use to point to a single
> htmlxref.cnf file, but was this variable supported starting from the
> same Texinfo version which introduced htmlxref.cnf?  It doesn't sound
> that way: htmlxref.cnf is mentioned in NEWS under Texinfo 5.0, whereas
> HTMLXREF_FILE is mentioned only under Texinfo 7.0.  So using this
> variable would mean we'd need to restrict HTML generation to Texinfo
> 7.0 and newer, right?

And one more question wrt what this section of the Texinfo manual
says: what exactly us the MANUAL part of the entries in htmlxref.cnf,
and what does texi2any compare it to?  For example, there's this entry
in the current file:

   smtp         mono    ${EMACS}/html_mono/smtpmail.html
   smtp         node    ${EMACS}/html_node/smtpmail/

What does "smtp" mean here?  The source file for this manual is
smtpmail.texi and the output goes to smptmail.html, so how is "smtp"
used by texi2any?  I'm asking because there are other manuals where
the name in the top-level DIR menu differs from the file name, and I
need to understand how to format those lines.  The file as distributed
by Texinfo seems to be somewhat inconsistent in this respect: for
example, in case of CL-LIB manual, the MANUAL part of the entry is
"cl", identical to the file name, in contrast to the above "smtp"
entry.  Perhaps "smtp" above is a mistake, and MANUAL should always
equal the file name?