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

[Mekeor Melire]

After a discussion on emacs-devel[1] and a discussion on a
bug-report[2], this was commited on the master-branch:

    756daa93b3ef7ce33e741ab30000fa397fcd9783
    Author:     Mekeor Melire <mekeor@posteo.de>
    AuthorDate: Mon Dec 4 16:37:37 2023 +0100
    Commit:     Eli Zaretskii <eliz@gnu.org>
    CommitDate: Sat Jan 27 12:18:17 2024 +0200

    Add option Info-url-alist

The new option Info-url-alist allow users to add custom mappings from
manual-names to URLs. When the URL-SPEC is provided as string, users may
use the %e format-sequence. But in the most common case, namely when
URLs need to use a .html-suffix, this is not usable:

In the case of the special "Top" node, the %e format-sequence resolves
to "", i.e. the empty string. It is thus not possible to use a URL-SPEC
like "https://example.com/%e.html"; because "https://example.com/.html";
is invalid. The user rather wants "https://example.com/index.html"; in
this case.

Currently, the user needs to choose to use a function as URL-SPEC in
this case. This works but is tedious, especially since this is the most
common case.

Thus, I suggest to provide another format-sequence to the
URL-SPEC-string: %i. It will resolve the "Top" node as "index", thus
allowing for "https://example.com/%i.html"; to be used as URL-SPEC.

Find attached a patch that does so, and also refills the doc-string.


[1]  https://lists.gnu.org/archive/html/emacs-devel/2023-11/msg01286.html

[2]  https://lists.gnu.org/archive/html/bug-gnu-emacs/2023-12/msg00156.html


>From 03752ac8f3b2c86dd81da21db4fb5981461af3e5 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Wed, 7 Feb 2024 14:47:07 +0100
Subject: [PATCH] Provide format-sequence %i in Info-url-for-node

* lisp/info.el (Info-url-for-node): Provide format-sequence %i which
resolves "Top" node as "index".
(Info-url-alist): Explain it in refilled docstring.
---
 lisp/info.el | 76 ++++++++++++++++++++++++++++++----------------------
 1 file changed, 44 insertions(+), 32 deletions(-)

diff --git a/lisp/info.el b/lisp/info.el
index e91cc7b8e54..7c58879e545 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -227,28 +227,35 @@ Info-url-alist
      "https://www.gnu.org/software/emacs/manual/html_node/%m/%e";))
   "Alist telling `Info-mode' where manuals are accessible online.
 
-Each element of this list has the form (MANUALs . URL-SPEC).
-MANUALs represents the name of one or more manuals.  It can
-either be a string or a list of strings.  URL-SPEC can be a
-string in which the substring \"%m\" will be expanded to the
-manual-name, \"%n\" to the node-name, and \"%e\" to the
-URL-encoded node-name (without a `.html' suffix).  (The
-URL-encoding of the node-name mimics GNU Texinfo, as documented
-at Info node `(texinfo)HTML Xref Node Name Expansion'.)
-Alternatively, URL-SPEC can be a function which is given
-manual-name, node-name and URL-encoded node-name as arguments,
-and is expected to return the corresponding URL as a string.
+Each element of this list has the form (MANUALs . URL-SPEC).  MANUALs
+represents the name of one or more manuals.  It can either be a string
+or a list of strings.  URL-SPEC can be a string in which the format
+sequences explained below can be used.  Alternatively, it can be a
+function which is given arguments corresponding to the format sequences
+below and is expected to return the corresponding URL as a string.
+
+`%m' represents the manual-name.
+
+`%n' represents the (raw) node-name.
+
+`%e' represents a URL-encoded node-name.  (The encoding mimics GNU
+     Texinfo, as documented at Info node `(texinfo)HTML Xref Node Name
+     Expansion'.)  It does not include any suffix like `.html'.  In case
+     of the `Top' node, it is the empty string.
+
+`%i' represents a URL-encoded node-name, which in case of the `Top'
+     node, is the string \"index\".
 
 This variable particularly affects the command
 `Info-goto-node-web', which see.
 
 The default value of this variable refers to the official,
 HTTPS-accessible HTML-representations of all manuals that Emacs
-includes.  These URLs refer to the most recently released version
-of Emacs, disregarding the version of the running Emacs.  In
-other words, the content of your local Info node and the
-associated online node may differ.  The resource represented by
-the generated URL may even be not found by the gnu.org server."
+includes.  These URLs refer to the most recently released version of
+Emacs, disregarding the version of the running Emacs.  In other words,
+the content of your local Info node and the associated online node may
+differ.  The resource represented by the generated URL may even be not
+found by the gnu.org server."
   :version "30.1"
   :type '(alist
            :tag "Mapping from manual-name(s) to URL-specification"
@@ -1922,26 +1929,31 @@ Info-url-for-node
              (encoded-node
                ;; Reproduce GNU Texinfo's way of URL-encoding.
                ;; (info "(texinfo) HTML Xref Node Name Expansion")
-               (if (equal node "Top")
-                 ""
-                 (url-hexify-string
-                   (string-replace " " "-"
-                     (mapconcat
-                       (lambda (ch)
-                         (if (or (< ch 32)      ; ^@^A-^Z^[^\^]^^^-
-                               (<= 33 ch 47)    ; !"#$%&'()*+,-./
-                               (<= 58 ch 64)    ; :;<=>?@
-                               (<= 91 ch 96)    ; [\]_`
-                               (<= 123 ch 127)) ; {|}~ DEL
-                           (format "_00%x" ch)
-                           (char-to-string ch)))
-                       node ""))))))
+               (url-hexify-string
+                 (string-replace " " "-"
+                   (mapconcat
+                     (lambda (ch)
+                       (if (or (< ch 32)      ; ^@^A-^Z^[^\^]^^^-
+                             (<= 33 ch 47)    ; !"#$%&'()*+,-./
+                             (<= 58 ch 64)    ; :;<=>?@
+                             (<= 91 ch 96)    ; [\]_`
+                             (<= 123 ch 127)) ; {|}~ DEL
+                         (format "_00%x" ch)
+                         (char-to-string ch)))
+                     node ""))))
+             (top-as-empty-node
+               (if (string= node "Top") "" encoded-node))
+             (top-as-index-node
+               (if (string= node "Top") "index" encoded-node)))
     (cond
       ((stringp url-spec)
         (format-spec url-spec
-          `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+          `((?m . ,manual) (?n . ,node)
+             (?e . ,top-as-empty-node)
+             (?i . ,top-as-index-node))))
       ((functionp url-spec)
-        (funcall url-spec manual node encoded-node))
+        (funcall url-spec manual node
+          top-as-empty-node top-as-index-node))
       (t (error "URL-specification neither string nor function")))
     (error "No URL-specification associated with manual-name `%s'"
       manual)))
-- 
2.41.0