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

[Eli Zaretskii]

> From: Mekeor Melire <mekeor@posteo.de>
> Cc: 68970@debbugs.gnu.org
> Date: Thu, 08 Feb 2024 20:20:18 +0000
> 
> 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.

Why should %e omit the .html extension in the first place?  What
problems will we cause if we make %e include the .html extension when
that is required, and omit it when it isn't (like when converting the
"Top" node)?

AFAICS, the use of %e in Emacs 29 doesn't add the .html extension to
the produced URLs, but would producing the .html extension from %e
cause any problems with the GNU manuals we had in Info-url-alist in
Emacs 29?  Do we know of any package which augments Info-url-alist
with specs that use %e.html?

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

I'm asking why cannot we make %e behave like your proposed %E?