Subject: bug#68970: closed (Re: [PATCH v2] In Info-url-alist, add .html extension to %e format-sequence)

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 11 Feb 2024 07:28:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
68970: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68970
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: [PATCH v2] In Info-url-alist, add .html extension to %e format-sequence
From: Eli Zaretskii <[email-masked]>
To: Mekeor Melire <[email-masked]>
Cc: [email-masked]
Date: Sun, 11 Feb 2024 09:27:31 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Mekeor Melire <[email-masked]>
> Cc: Eli Zaretskii <[email-masked]>
> Date: Sat, 10 Feb 2024 22:41:35 +0000
> 
> > if the doc string looks okay to you, there's no need to refill.
> 
> I decided to not refill the docstring.
> 
> > > > Two spaces between sentences, please.
> 
> Done.
> 
> > > > Should we add here tests for the Top node?
> 
> Done.
> 
> Find attached the new version of the patch.

Thanks, installed on the master branch, and closing the bug.

Subject: 30.0.50; Info.el: Info-url-alist should support format-sequence that encodes "Top" node as "index"
From: Mekeor Melire <[email-masked]>
To: [email-masked]
Date: Wed, 07 Feb 2024 13:27:35 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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 <[email-masked]>
    AuthorDate: Mon Dec 4 16:37:37 2023 +0100
    Commit:     Eli Zaretskii <[email-masked]>
    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 <[email-masked]>
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