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