Re: Texinfo 7.0 changed the name of HTML output directory

[Gavin Smith]

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

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

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.



> 
> > This could potentially break some use cases, but I think they would be
> > rare.  The common case is that the output directory, e.g. "eglot_html",
> > would be renamed to e.g. "eglot" when installed on a website.   The
> > purpose of this change was certainly not to change locations of web pages.
> 
> If the common case is to rename "eglot_html" to "eglot", then why is
> the default "eglot_html"?  In my book, defaults should be identical to
> what happens in common cases, otherwise we force everyone and their
> dog to customize texi2any.  No?

I assume that the "_html" suffix marks the output directory as containing
HTML so is useful to have when the HTML output appears among other files
in a directory on someone's computer.


>  IOW, I'd expect the version of
> htmlxref.cnf distributed by Texinfo to be mostly empty, with the
> possible exception of G and GS variables, and possibly other such
> variables that document the site of each manual, like BINUTILS, EMACS,
> etc. -- so that cross-manual references that point to another project
> could be correct.  But the "manual information" lines should not be
> present in this file for most if not all manuals, AFAUI, if the
> defaults are reasonable.

It is only two links, "mono" and "node" for most manuals and we have
to say which webpage the manuals are found on.  I doubt there is
much benefit to trying to abbreviate the htmlxref.cnf format any, if
I understand what you said correctly.

> 
> Maybe.  I don't see this renaming in any of the scripts involved in
> generating and uploading of the Emacs manuals, but maybe I'm missing
> something.

It could also be done with the "-o" option to texi2any.

> 
> > I suspect that the online organisation of the Emacs manuals is slightly
> > different to that of other projects and changing the default to
> > "../eglot/" instead of "../eglot_html/" would benefit Emacs but few if
> > any other projects.
> 
> Please elaborate.  I don't understand how this can be relevant only to
> Emacs.  The only thing that is special to Emacs is that it has many
> more manuals than other GNU projects, and maybe more cross-manual
> references, but other than that, this should be relevant to any
> project that has cross-manual references.

For example, the GNU automake manual links to the GNU autoconf manual.  The
page

https://www.gnu.org/software/automake/manual/html_node/Introduction.html

contains a link to

https://www.gnu.org/software/autoconf/manual/html_node/index.html#Top

Making this link "../autoconf/index.html#Top"
(or "../autoconf_html/index.html#Top") would not work.

It would have to be "../../../autoconf/manual/html_node/index.html#Top".

Looking at htmlxref.cnf there are some projects that have similar
directory layouts to Emacs.  For example, gnupg:

GNUPG = https://www.gnupg.org/documentation/manuals
gnupg           node    ${GNUPG}/gnupg/
 dirmngr        node    ${GNUPG}/dirmngr/
 gcrypt         node    ${GNUPG}/gcrypt/
 libgcrypt      node    ${GNUPG}/gcrypt/
 ksba           node    ${GNUPG}/ksba/
 assuan         node    ${GNUPG}/assuan/
 gpgme          node    ${GNUPG}/gpgme/

Since all these manuals are in the same top-level directory they
would have the same issue as the Emacs manuals.

Changing the way texi2any outputs such links seems easy to implement.
In Texinfo 6.8, in HTML.pm:_external_node_href, the following lines
gave the default output:


   if ($target_split) {
      if (defined($href)) {
        $file = $href;
      } elsif (defined($self->get_conf('EXTERNAL_DIR'))) {
        $file = $self->get_conf('EXTERNAL_DIR')."/$manual_base";
      } elsif ($self->get_conf('SPLIT')) {
        $file = "../$manual_base";
      }
      $file .= "/";
    } else {# target not split

Notable, the line

        $file = "../$manual_base";

shows the manual name without a suffix.

In Texinfo 7.1, this had become:

    if ($target_split) {
      if (defined($href)) {
        $directory = $href;
      } else {
        my $manual_dir = $manual_base;
        if (defined($self->{'output_format'}) and $self->{'output_format'} ne 
'') {
          $manual_dir .= '_'.$self->{'output_format'};
        }
        if (defined($self->get_conf('EXTERNAL_DIR'))) {
          $directory = $self->get_conf('EXTERNAL_DIR')."/$manual_dir";
        } elsif ($self->get_conf('SPLIT')) {
          $directory = "../$manual_dir";
        }
        $directory = $self->url_protect_file_text($directory);
      }
      $directory .= "/";
    } else {# target not split


The line

          $manual_dir .= '_'.$self->{'output_format'};

appends a suffix.

We might need to go back to the way it was done before and not append
this suffix.  I don't know if it is worth adding a customization variable
for this.