bug#68970: 30.0.50; Info.el: Info-url-alist should support format-sequence that encodes "Top" node as "index"

[Mekeor Melire]

2024-02-08 08:26 eliz@gnu.org:

> I tried several of those, and they all work without index.html.  For
> example, these work for me:
>
>   https://sourceware.org/gdb/current/onlinedocs/gdb
>   https://sourceware.org/gdb/current/onlinedocs/annotate
>   https://sourceware.org/gdb/current/onlinedocs/stabs
>   https://cc-mode.sourceforge.net/html-manual
>   https://orgmode.org/manual
>
> Some of them also work with a trailing slash, some don't.

Thank you for taking time to try it out.

Sorry that I was not precise in my statement. You are right,
"index.html" can be omitted.[1]

But let me try to explain what I really meant. Let's look at a node
named "Summary". Texinfo will generate a "Summary.html" file for it. For
this file, some webservers do not allow to omit the .html suffix when
requesting it via HTTP. For example:

    https://sourceware.org/gdb/current/onlinedocs/gdb/Summary
    -> error 404, not found

    https://sourceware.org/gdb/current/onlinedocs/gdb/Summary.html
    -> works fine

Thus, for the GDB manual, the user would consider to use

    https://sourceware.org/gdb/current/onlinedocs/gdb/%e.html

because %e does not contain the .html-suffix and because the webserver
requires to keep the .html-suffix for non-index-HTMLs. But that
URL-specification would not work in case of the "Top"-node because %e
will be substituted with the empty string "" in that case, thus
yielding:

    https://sourceware.org/gdb/current/onlinedocs/gdb/.html
    -> error 404, not found

The user would now understand that, with the restrictions of the current
implementation of the feature, they must define a custom function and
use it as URL-specification for the GDB-manual.

> > Another idea would be to let users specify two URL-SPECs: One for the
> > Top-node; another for non-Top nodes.
>
> I'd prefer this latter alternative.

Having thought about this idea again, it seems unnecessary because we
know that the "Top" node is always translated as "index.html". Here's a
quote from (info "(texinfo) HTML Xref Node Name Expansion"):

    A special exception: the Top node (*note The Top Node) is always
    mapped to the file 'index.html', to match web server software.

As a result, I'd like to propose yet another approach. Currently, the
implementation on the master branch offers %m (manual-name), %n (raw
node-name) and %e (URL-encoded node-name without .html-suffix). Let's
add the format-sequence %E that does include the .html-suffix. In case
of the Top-node, it'll be the empty-string "", i.e. it'll behave just
like %e in that case.

| node  | %e    | %E         |
|-------+-------+------------|
| "Top" | ""    | ""         |
| "Foo" | "Foo" | "Foo.html" |

The gnu.org webserver is configured to allow omission of the
.html-suffix. We can thus use the %e format-sequence:

| URL-specification    | https://gnu.org/s/emacs/manual/html_node/emacs/%e    |
|----------------------+------------------------------------------------------|
| URL for "Top" node   | https://gnu.org/s/emacs/manual/html_node/emacs/      |
| URL for "Intro" node | https://gnu.org/s/emacs/manual/html_node/emacs/Intro |

The sourceware.org does not allow to omit the .html-suffix. But it
allows to omit "index.html". We can thus use %E:

| URL-specification      | https://sourceware.org/gdb/current/onlinedocs/gdb/%E 
          |
|------------------------+----------------------------------------------------------------|
| URL for "Top" node     | https://sourceware.org/gdb/current/onlinedocs/gdb/   
          |
| URL for "Summary" node | 
https://sourceware.org/gdb/current/onlinedocs/gdb/Summary.html |

I think with these format-sequences we'd cover a lot of cases.

We would not cover the case when the webserver does not allow to omit
"index.html" but this is a very uncommon case. Thus, it'd be fine when
users need to use a custom function as URL-specification.



[1]  Of course, webservers can be configured to not serve index.html
     when a directory is requested. But the default is to do so.

     When using the common Apache webserver, one can disable this
     "defaulting to index.html" with the "DirectoryIndex disabled"
     directive, as documented here:

     https://httpd.apache.org/docs/trunk/mod/mod_dir.html#directoryindex