Re: Texinfo 7.0 changed the name of HTML output directory

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Fri, 23 Aug 2024 17:18:25 +0100
> Cc: bug-texinfo@gnu.org
> 
> On Fri, Aug 23, 2024 at 09:25:40AM +0300, Eli Zaretskii wrote:
> > > I notice that "eglot" is not listed in "htmlxref.cnf" so will be output
> > > with a default.  The HTML source has
> > > 
> > > <a data-manual="eglot" 
> > > href="../eglot_html/Eglot-Features.html#Eglot-Features">Eglot Features</a>
> > > 
> > > for the link.  The code in texi2any (in HTML.pm, _external_node_href)
> > > suffixes the manual name with an underscore and the output format ("html")
> > > when generating this hyperlink.
> > 
> > Sorry, you lost me here.  Emacs doesn't have an htmlxref.cnf file,
> > AFAICS.  Are you saying that we need to make sure the file distributed
> > by Texinfo is up-to-date with the structure of the Emacs manuals, and
> > that this up-to-date file is present on the system where the HTMl
> > manuals are generated?  That sounds like an unnecessary maintenance
> > burden, both for us and for you.
> 
> That is the way that inter-manual links have been supported up to the
> current point in time, yes.
> 
> 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?

This is all quite annoying, to tell the truth.  The only practical
alternative seems to be to generate the HTML manuals using the
system-wide htmlxref.cnf file, and then use our own script to edit all
the instances of "MANUAL_html/" to say "MANUAL/" instead, which
basically means we don't use any of the facilities provided by Texinfo
for this purpose.  Or am I missing something?

> > > There are actually two different questions:
> > > * What name to use for the output directory
> > > * What name to use in cross-references by default
> > > 
> > > These could be different.  We could keep the output directory as
> > > "eglot_html" while changing the hyperlink to refer to, simply, "eglot".
> > 
> > Can you explain how this could work?  I always thought that these
> > parts of each URL must reflect the actual directory structure of the
> > filesystem where the HTML files reside.
> 
> The idea is that the output directory MANUAL_html would be renamed to
> MANAUL when uploaded to the website.

That's a tough requirement when using a VCS to host the manuals, as
the entire GNU project does.  CVS doesn't support file renaming, so we
lose all the history when renaming a directory.  So renaming the
existing directories is not an option for us.

> What has caused the problem you are reporting is not actually the
> output directory having the "_html" suffix, but this suffix appearing
> in intermanual links.

AFAIU, in order to work, the links and the directory structure must
use the same conventions, otherwise there are significant
complications (like redirection files etc.).  So we must make sure the
links use MANUAL, not MANUAL_html.  Using the --output command-line
option (which we do) does not solve this problem, as it only affects
where the output files are being written, not the cross-reference
links.