From: Mekeor Melire <mekeor@posteo.de>
To: 68970@debbugs.gnu.org
Subject: bug#68970: 30.0.50; Info.el: Info-url-alist should support format-sequence that encodes "Top" node as "index"
Date: Wed, 07 Feb 2024 13:27:35 +0000 [thread overview]
Message-ID: <87fry44bz6.fsf@posteo.de> (raw)
[-- Attachment #1: Type: text/plain, Size: 1515 bytes --]
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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Provide-format-sequence-i-in-Info-url-for-node.patch --]
[-- Type: text/x-patch, Size: 5488 bytes --]
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
next reply other threads:[~2024-02-07 13:27 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-02-07 13:27 Mekeor Melire [this message]
2024-02-07 14:51 ` bug#68970: 30.0.50; Info.el: Info-url-alist should support format-sequence that encodes "Top" node as "index" Eli Zaretskii
2024-02-07 19:52 ` Mekeor Melire
2024-02-07 20:18 ` Eli Zaretskii
2024-02-07 22:10 ` Mekeor Melire
2024-02-08 6:26 ` Eli Zaretskii
2024-02-08 20:20 ` Mekeor Melire
2024-02-09 7:02 ` Eli Zaretskii
2024-02-09 22:00 ` bug#68970: [PATCH] In Info-url-alist, add .html extension to %e format-sequence Mekeor Melire
2024-02-10 7:46 ` Eli Zaretskii
2024-02-10 13:16 ` Mekeor Melire
2024-02-10 13:56 ` Eli Zaretskii
2024-02-10 22:41 ` bug#68970: [PATCH v2] " Mekeor Melire
2024-02-11 7:27 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fry44bz6.fsf@posteo.de \
--to=mekeor@posteo.de \
--cc=68970@debbugs.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.