* bug#67615: [PATCH] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
@ 2023-12-04 0:04 Mekeor Melire
2023-12-04 0:30 ` Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-04 0:04 UTC (permalink / raw)
To: 67615
This is my first patch to Emacs. I probably made some mistakes regarding the many conventions. I tried my best, including regarding the code formatting. Also, I hope that my mail client is configured well and formats the patch well. Last but not least, note that my FSF-copyright-assignment is still ongoing.
---
ChangeLog.4 | 7 ++++
etc/NEWS | 8 ++++
lisp/info.el | 101
++++++++++++++++++++++++++++++++++++++-------------
3 files changed, 90 insertions(+), 26 deletions(-)
diff --git a/ChangeLog.4 b/ChangeLog.4
index 24afabdbbb1..6e54264a32b 100644
--- a/ChangeLog.4
+++ b/ChangeLog.4
@@ -1,3 +1,10 @@
+2023-12-03 Mekeor Melire <mekeor@posteo.de>
+
+ Support online-browsing all Emacs-contained manuals.
+
+ * lisp/info.el (Info-urls): New defcustom that maps
manual-names
+ to URL-specifications.
+
2023-10-16 Po Lu <luangruo@yahoo.com>
Correctly register focus events concomitant with alpha changes
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..6b5928bd74e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -356,6 +356,14 @@ respectively, in addition to the existing
translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-urls'.
+Browse any online info manual, not just the 'emacs' and 'elisp'
+manuals. By default, allow browsing online info manuals of all
+Emacs-contained manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command. Note
that
diff --git a/lisp/info.el b/lisp/info.el
index 51e9eb72edf..0e16ee7340c 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,45 @@ Info-additional-directory-list
These directories are searched after those in
`Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-urls
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus"
"dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot"
"eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa"
"erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gawk"
"gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix" "mairix-el"
+ "message" "mh-e" "modus-themes" "newsticker" "nxml-mode"
+ "octave-mode" "org" "pcl-cvs" "pgg" "rcirc" "reftex"
"remember"
+ "sasl" "sc" "semantic" "ses" "sieve" "smtpmail" "speedbar"
+ "srecode" "todo-mode" "tramp" "transient" "url"
"use-package"
+ "vhdl-mode" "vip" "viper" "vtable" "widget" "wisent"
"woman") .
+
"https://www.gnu.org/software/emacs/manual/html_node/%m/%n.html"))
+ "Alist telling `Info-mode' where manuals are accessible online.
+
+Each element of this list should match the pattern (MANUALS
+. URL-SPEC). MANUALS represents the name of one or many
+manuals. It should either be a string or a list of
+strings. URL-SPEC should be a string in which the substring
+\"%m\" will be expanded to the manual-name, and \"%n\" to the
+URL-encoded node-name. This URL-encoding of the node-name matches
+Texinfo's HTML cross-reference node name
+expansion. Alternatively, URL-SPEC can be the symbol of a
+function receiving the manual-name, the node-name and the
+URL-encoded node-name as arguments, returning a URL as string.
+
+The default value of this variable refers to the HTTP-accessible
+HTML-manuals of all manuals that Emacs includes. Specifically,
+the URL refers to the latest version of Emacs, disregarding the
+locally installed version."
+ :type '(alist
+ :tag "Mapping from manual-name(s) to
URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names"
string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function-item
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu
visits subnodes.
@@ -1807,33 +1846,43 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp
manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return a URL for NODE. NODE should be a string of the form
+\"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (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
- ""))
- (concat
"https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-"
node))
- ".html")))))
+ (error "Invalid node-name %s" node))
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (matched-pair (seq-find
+ (lambda (pair)
+ (seq-contains (ensure-list (car
pair))
+ manual
#'string-equal-ignore-case))
+ Info-urls)))
+ (if-let* ((encoded-node
+ ;; Reproduce GNU Texinfo's way of URL-encoding.
+ ;; (info "(texinfo) HTML Xref Node Name
Expansion")
+ (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-spec (cdr matched-pair))
+ (url-spec (cond
+ ((functionp url-spec)
+ (funcall url-spec
+ manual node encoded-node))
+ ((stringp url-spec) url-spec))))
+ (format-spec url-spec `((?m . ,manual) (?n .
,encoded-node)))
+ (error "`Info-urls' associates an invalid URL-specification
with manual-name \"%s\"."
+ manual))
+ (error "`Info-urls' does not associate any URL-specification
with manual-name \"%s\"."
+ manual)))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-04 0:04 bug#67615: [PATCH] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Mekeor Melire
@ 2023-12-04 0:30 ` Mekeor Melire
2023-12-04 10:02 ` bug#67615: [PATCH v2] " Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-04 0:30 UTC (permalink / raw)
To: 67615
2023-12-04 00:04 mekeor@posteo.de:
> I hope that my mail client is configured well and formats the
> patch well.
Apparently, format=flowed is a bad idea for Git patches. Sorry. I'll resend soon.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-04 0:30 ` Mekeor Melire
@ 2023-12-04 10:02 ` Mekeor Melire
2023-12-04 15:51 ` Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-04 10:02 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
[-- Attachment #1: Type: text/plain, Size: 139 bytes --]
Here's another attempt to send my patch; this time, without
format=flowed. I hope it works now. In any case, sorry for the
inconvenience.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-info.el-Info-url-for-node-Support-all-Emacs-inf.patch --]
[-- Type: text/x-patch, Size: 7279 bytes --]
From 2f91e43aadaa6d23df4df9c676e19de27cad6404 Mon Sep 17 00:00:00 2001
From: user <>
Date: Mon, 4 Dec 2023 00:47:00 +0100
Subject: [PATCH] * lisp/info.el (Info-url-for-node): Support all Emacs info
manuals.
---
ChangeLog.4 | 7 ++++
etc/NEWS | 8 ++++
lisp/info.el | 101 ++++++++++++++++++++++++++++++++++++++-------------
3 files changed, 90 insertions(+), 26 deletions(-)
diff --git a/ChangeLog.4 b/ChangeLog.4
index 24afabdbbb1..6e54264a32b 100644
--- a/ChangeLog.4
+++ b/ChangeLog.4
@@ -1,3 +1,10 @@
+2023-12-03 Mekeor Melire <mekeor@posteo.de>
+
+ Support online-browsing all Emacs-contained manuals.
+
+ * lisp/info.el (Info-urls): New defcustom that maps manual-names
+ to URL-specifications.
+
2023-10-16 Po Lu <luangruo@yahoo.com>
Correctly register focus events concomitant with alpha changes
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..6b5928bd74e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -356,6 +356,14 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-urls'.
+Browse any online info manual, not just the 'emacs' and 'elisp'
+manuals. By default, allow browsing online info manuals of all
+Emacs-contained manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command. Note that
diff --git a/lisp/info.el b/lisp/info.el
index 51e9eb72edf..0e16ee7340c 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,45 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-urls
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gawk" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix" "mairix-el"
+ "message" "mh-e" "modus-themes" "newsticker" "nxml-mode"
+ "octave-mode" "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember"
+ "sasl" "sc" "semantic" "ses" "sieve" "smtpmail" "speedbar"
+ "srecode" "todo-mode" "tramp" "transient" "url" "use-package"
+ "vhdl-mode" "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "https://www.gnu.org/software/emacs/manual/html_node/%m/%n.html"))
+ "Alist telling `Info-mode' where manuals are accessible online.
+
+Each element of this list should match the pattern (MANUALS
+. URL-SPEC). MANUALS represents the name of one or many
+manuals. It should either be a string or a list of
+strings. URL-SPEC should be a string in which the substring
+\"%m\" will be expanded to the manual-name, and \"%n\" to the
+URL-encoded node-name. This URL-encoding of the node-name matches
+Texinfo's HTML cross-reference node name
+expansion. Alternatively, URL-SPEC can be the symbol of a
+function receiving the manual-name, the node-name and the
+URL-encoded node-name as arguments, returning a URL as string.
+
+The default value of this variable refers to the HTTP-accessible
+HTML-manuals of all manuals that Emacs includes. Specifically,
+the URL refers to the latest version of Emacs, disregarding the
+locally installed version."
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function-item
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1846,43 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return a URL for NODE. NODE should be a string of the form
+\"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (error "Invalid node-name %s" node))
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (matched-pair (seq-find
+ (lambda (pair)
+ (seq-contains (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-urls)))
+ (if-let* ((encoded-node
+ ;; Reproduce GNU Texinfo's way of URL-encoding.
+ ;; (info "(texinfo) HTML Xref Node Name Expansion")
+ (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-spec (cdr matched-pair))
+ (url-spec (cond
+ ((functionp url-spec)
+ (funcall url-spec
+ manual node encoded-node))
+ ((stringp url-spec) url-spec))))
+ (format-spec url-spec `((?m . ,manual) (?n . ,encoded-node)))
+ (error "`Info-urls' associates an invalid URL-specification with manual-name \"%s\"."
+ manual))
+ (error "`Info-urls' does not associate any URL-specification with manual-name \"%s\"."
+ manual)))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-04 10:02 ` bug#67615: [PATCH v2] " Mekeor Melire
@ 2023-12-04 15:51 ` Mekeor Melire
2023-12-04 16:24 ` Eli Zaretskii
` (2 more replies)
0 siblings, 3 replies; 23+ messages in thread
From: Mekeor Melire @ 2023-12-04 15:51 UTC (permalink / raw)
To: 67615
Please do not yet commit this patch. There are some TODOs left:
- Remove "gawk" and "mairix" manual-names from default value of
Info-urls since they response with HTTP status "not found".
- Check if there are more Emacs-included manuals, perhaps ones that are
not "one page per node".
- Improve and revisit NEWS, CHANGELOG and commit message.
- Adhere to fill-column.
- FSF copyright assignment.
Also I have some questions:
- What do you think about the naming of the Info-urls variable?
- Is the position of the definition of Info-urls fine?
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-04 15:51 ` Mekeor Melire
@ 2023-12-04 16:24 ` Eli Zaretskii
2023-12-05 1:06 ` bug#67615: Org-Mode story on how I gathered the list of Emacs-contained online-manuals Mekeor Melire
2023-12-07 2:48 ` bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Richard Stallman
2023-12-08 0:15 ` bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs Mekeor Melire
2 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2023-12-04 16:24 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
> From: Mekeor Melire <mekeor@posteo.de>
> Date: Mon, 04 Dec 2023 15:51:32 +0000
>
> Please do not yet commit this patch. There are some TODOs left:
>
> - Remove "gawk" and "mairix" manual-names from default value of
Gawk and mairix are not parts of Emacs, they are separately-maintained
programs. So their manuals cannot be reached via the common base of
the Emacs manuals, and therefore they should not be in that list,
indeed.
> Info-urls since they response with HTTP status "not found".
> - Check if there are more Emacs-included manuals, perhaps ones that are
> not "one page per node".
> - Improve and revisit NEWS, CHANGELOG and commit message.
> - Adhere to fill-column.
> - FSF copyright assignment.
>
> Also I have some questions:
>
> - What do you think about the naming of the Info-urls variable?
> - Is the position of the definition of Info-urls fine?
I will review the patch in a couple of days, so if you have more
changes, please feel free to post updated patches. There's no rush.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: Org-Mode story on how I gathered the list of Emacs-contained online-manuals
2023-12-04 16:24 ` Eli Zaretskii
@ 2023-12-05 1:06 ` Mekeor Melire
0 siblings, 0 replies; 23+ messages in thread
From: Mekeor Melire @ 2023-12-05 1:06 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 67615
[-- Attachment #1: Type: text/plain, Size: 994 bytes --]
2023-12-04 18:24 eliz@gnu.org:
> > From: Mekeor Melire <mekeor@posteo.de>
> > Date: Mon, 04 Dec 2023 15:51:32 +0000
> >
> > - Remove "gawk" and "mairix" manual-names from default value of
>
> Gawk and mairix are not parts of Emacs, they are separately-maintained
> programs. So their manuals cannot be reached via the common base of
> the Emacs manuals, and therefore they should not be in that list,
> indeed.
For Gawk, my heuristics for gathering the list of manuals failed for an
unknown reason.
For mairix, it's "mairix" in
https://www.gnu.org/software/emacs/manual/mairix.html but "mairix-el" in
https://www.gnu.org/software/emacs/manual/html_node/mairix-el/index.html
but I don't know why. That's why my heuristics failed here too. But
yeah, "mairix-el" is the right one.
To ensure a complete list, I revisited my heuristics and wrote a little
story with Org Mode how I gathered the list of Emacs-included
online-manuals. Anyone who's really interested, can read the attachment.
:D
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: story.org --]
[-- Type: text/x-org, Size: 6306 bytes --]
* Sources
Let's gather a list of Emacs-included manuals from different sources.
** Included of Guix-installed Emacs
Gather a list of manuals that an Guix-installed Emacs includes:
#+begin_src sh :results raw :wrap
for f in $(find $(guix package -I | grep emacs-next | cut -f 4)/share/info -type f); do
basename $f | cut -d . -f 1
done | sort
#+end_src
#+NAME: from_guix
#+results:
#+begin_results
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results
rcirc
vtable
vhdl-mode
ses
ido
mh-e
ccmode
efaq
info
sieve
emacs-gnutls
mairix-el
calc
widget
message
transient
cl
forms
autotype
htmlfontify
elisp
pgg
ebrowse
wisent
auth
newsticker
pcl-cvs
erc
sc
org
nxml-mode
remember
ediff
vip
dired-x
bovine
emacs-mime
epa
edt
semantic
eshell
use-package
gnus
viper
ert
speedbar
srecode
eww
woman
idlwave
eudc
todo-mode
dbus
eieio
eintr
ede
eglot
modus-themes
octave-mode
url
flymake
smtpmail
emacs
sasl
reftex
tramp
** Mentioned on gnu.org
Gather a list of Emacs-included manuals by parsing https://www.gnu.org/software/emacs/manual/.
#+begin_src elisp
(string-join
(sort
(seq-map #'cadr
(s-match-strings-all "href=\"\\([a-zA-Z0-9_-]+\\)\.html"
(plz 'get "https://www.gnu.org/software/emacs/manual/")))
#'string<)
"\n")
#+end_src
#+NAME: from_gnu_org
#+RESULTS:
#+begin_example
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_example
** Checked into emacs repository
Gather a list of Emacs-included manuals from Emacs' repository; from a local clone in particular.
#+begin_src sh :results raw :wrap
find ~/store/host/permanent/git/foreign/emacs/doc/misc/ -type f -iname '*.texi' -exec basename \{\} .texi \; | sort
#+end_src
#+NAME: from_repo
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
cc-mode
cl
dbus
dired-x
doclicense
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
gnus-faq
gpl
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
newsticker
nxml-mode
octave-mode
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
sem-user
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
trampver
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results
* Merge manual-lists from all sources
Merge all sources; make sure each manual-name is unique.
#+begin_src sh :var from_guix=from_guix :var from_gnu_org=from_gnu_org :var from_repo=from_repo :results raw :wrap
for m in $from_guix $from_gnu_org $from_repo; do
echo $m
done | sort | uniq
#+end_src
#+NAME: merged
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
cc-mode
ccmode
cl
dbus
dired-x
doclicense
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
gnus-faq
gpl
htmlfontify
idlwave
ido
info
mairix
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
sem-user
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
trampver
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results
* Check online availability of each manual
** Filter manuals with "one page per node" online-manuals
#+begin_src sh :var manuals=merged :results raw :wrap
for m in $manuals; do
if [ 200 = "$(curl -s -i https://www.gnu.org/software/emacs/manual/html_node/$m/index.html | head -n 1 | cut -d ' ' -f 2)" ]; then
echo $m;
fi
done
#+end_src
#+NAME: available_per_node
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results
** Filter manuals with "entirely on one page" online-manuals
Find out if there are manuals that do not have a "one page per node" online-manual, but have only a "entirely on one page" online-manual. It could be!
First, determine those manuals without "one page per node" online-manuals:
#+begin_src sh :var merged=merged :var available_per_node=available_per_node :results raw :wrap
for m in $merged $available_per_node; do echo $m; done | sort | uniq -c | grep ' 1 ' | rev | cut -d ' ' -f 1 | rev
#+end_src
#+NAME: not_available_per_node
#+RESULTS:
#+begin_results
cc-mode
doclicense
gnus-faq
gpl
mairix
sem-user
trampver
#+end_results
Well, these manuals are known to not exist because of following reasons:
- cc-mode: It's =cc-mode.texi= but =ccmode.info=: https://git.sv.gnu.org/cgit/emacs.git/tree/doc/misc/cc-mode.texi?h=88a6209a7f881b6cab5f1fd9761f1b8ae7cad6fa#n84
- doclicense: Only used via ~@include ....texi~
- gnus-faq: Only used via ~@include ....texi~
- gpl: Only used via ~@include ....texi~
- mairix: It's "mairix" in https://www.gnu.org/software/emacs/manual/mairix.html but "mairix-el" in https://www.gnu.org/software/emacs/manual/html_node/mairix-el/index.html
- sem-user: Only used via ~@include ....texi~
- trampver: Only used via ~@include ....texi~
Thus, there is no (online-)manual for these texi-files, particularly no "entirely on one page" online-manual.
* Conclusion
See results named =available_per_node= for list of all Emacs-included online manuals.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-04 15:51 ` Mekeor Melire
2023-12-04 16:24 ` Eli Zaretskii
@ 2023-12-07 2:48 ` Richard Stallman
2023-12-07 7:19 ` Eli Zaretskii
2023-12-08 0:15 ` bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs Mekeor Melire
2 siblings, 1 reply; 23+ messages in thread
From: Richard Stallman @ 2023-12-07 2:48 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> - Remove "gawk" and "mairix" manual-names from default value of
> Info-urls since they response with HTTP status "not found".
What is the intended meaning of Info-urls? What is the criterion for
what to include, and what is the reason for choosing that criterion?
I ask becaise Gawk is a GNU package. It is reasonable, as a matter of
general principle, for Emacs to refer people to GAWK and its
documentation.
Whether it is useful to do so _in this specific case_, I don't have an
opinion about, because I don't know ebough about this specific case.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-07 2:48 ` bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Richard Stallman
@ 2023-12-07 7:19 ` Eli Zaretskii
2023-12-07 11:56 ` Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2023-12-07 7:19 UTC (permalink / raw)
To: rms; +Cc: mekeor, 67615
> Cc: 67615@debbugs.gnu.org
> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 06 Dec 2023 21:48:52 -0500
>
> > - Remove "gawk" and "mairix" manual-names from default value of
> > Info-urls since they response with HTTP status "not found".
>
> What is the intended meaning of Info-urls? What is the criterion for
> what to include, and what is the reason for choosing that criterion?
>
> I ask becaise Gawk is a GNU package. It is reasonable, as a matter of
> general principle, for Emacs to refer people to GAWK and its
> documentation.
We decided first to support manuals that come with Emacs, and Gawk's
manual doesn't.
Supporting all GNU manuals is a much larger job, since there's no
single base URL from which they all can be reached (although many of
them can be reached from the GNU site). Also, the arrangement of the
manuals of the other packages is slightly different from that of
Emacs, which needs more specialized processing.
So I think for now it should be enough to have only the Emacs manuals
by default, and let users add more associations for other packages if
they like.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-07 7:19 ` Eli Zaretskii
@ 2023-12-07 11:56 ` Mekeor Melire
2023-12-07 17:02 ` Eli Zaretskii
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-07 11:56 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 67615, rms
2023-12-07 09:19 eliz@gnu.org:
> We decided first to support manuals that come with Emacs, and Gawk's
> manual doesn't.
>
> Supporting all GNU manuals is a much larger job, since there's no
> single base URL from which they all can be reached (although many of
> them can be reached from the GNU site). Also, the arrangement of the
> manuals of the other packages is slightly different from that of
> Emacs, which needs more specialized processing.
It would be of great help if the administrators of gnu.org could provide
a strict pattern for online-manual-URLs on gnu.org. Additionally, it'd
be nice if gnu.org would not only provide the manual for the latest
version of GNU packages, but also for prior versions. This would allow
Emacs' info.el to browse the version-matching online-manual
corresponding to the locally-installed, currently-read Emacs-included
manual. But all of this needs to be discussed on another mailing-list,
related to the administration of gnu.org.
> So I think for now it should be enough to have only the Emacs manuals
> by default, and let users add more associations for other packages if
> they like.
By the way, I'm planning to release a FSF-assigned Emacs-package
providing more associations.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-07 11:56 ` Mekeor Melire
@ 2023-12-07 17:02 ` Eli Zaretskii
2023-12-09 4:05 ` Richard Stallman
0 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2023-12-07 17:02 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615, rms
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: rms@gnu.org, 67615@debbugs.gnu.org
> Date: Thu, 07 Dec 2023 11:56:34 +0000
>
> 2023-12-07 09:19 eliz@gnu.org:
>
> > We decided first to support manuals that come with Emacs, and Gawk's
> > manual doesn't.
> >
> > Supporting all GNU manuals is a much larger job, since there's no
> > single base URL from which they all can be reached (although many of
> > them can be reached from the GNU site). Also, the arrangement of the
> > manuals of the other packages is slightly different from that of
> > Emacs, which needs more specialized processing.
>
> It would be of great help if the administrators of gnu.org could provide
> a strict pattern for online-manual-URLs on gnu.org. Additionally, it'd
> be nice if gnu.org would not only provide the manual for the latest
> version of GNU packages, but also for prior versions. This would allow
> Emacs' info.el to browse the version-matching online-manual
> corresponding to the locally-installed, currently-read Emacs-included
> manual. But all of this needs to be discussed on another mailing-list,
> related to the administration of gnu.org.
I think each GNU project uses slightly different arrangements. Also,
how exactly the HTML manuals are arranged on gnu.org is up to the
projects, not gnu.org admmins (which just provide technical support).
In any case, this is not the right place to talk about GNU-wide
conventions and decisions.
> > So I think for now it should be enough to have only the Emacs manuals
> > by default, and let users add more associations for other packages if
> > they like.
>
> By the way, I'm planning to release a FSF-assigned Emacs-package
> providing more associations.
That is okay, but one problem with such associations is the need to
maintain them so they remain accurate, tracking whatever changes in
other GNU projects that could affect this. This is one reason I
suggested that we stop short of doing that, and only limit ourselves
to the manuals which we control.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-04 15:51 ` Mekeor Melire
2023-12-04 16:24 ` Eli Zaretskii
2023-12-07 2:48 ` bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Richard Stallman
@ 2023-12-08 0:15 ` Mekeor Melire
2023-12-09 9:42 ` Eli Zaretskii
2 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-08 0:15 UTC (permalink / raw)
To: 67615; +Cc: Eli Zaretskii
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-lisp-info.el-Info-url-alist-New-option-mapping-manua.patch --]
[-- Type: text/x-patch, Size: 7413 bytes --]
From 1e9b31174ab4cfb2edb73f23aa1a3ec86943ba42 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
to URLs.
---
ChangeLog.4 | 8 +++++
etc/NEWS | 9 +++++
lisp/info.el | 100 ++++++++++++++++++++++++++++++++++++++++-----------
3 files changed, 96 insertions(+), 21 deletions(-)
diff --git a/ChangeLog.4 b/ChangeLog.4
index 24afabdbbb1..0aabd9f52bb 100644
--- a/ChangeLog.4
+++ b/ChangeLog.4
@@ -1,3 +1,11 @@
+2023-12-08 Mekeor Melire <mekeor@posteo.de>
+
+ Support online-browsing all Emacs-contained manuals or any other.
+
+ * lisp/info.el (Info-url-alist): New defcustom that maps
+ manual-names to URL-specifications.
+ (Info-url-for-node): Use it.
+
2023-10-16 Po Lu <luangruo@yahoo.com>
Correctly register focus events concomitant with alpha changes
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..4730cc3a351 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -356,6 +356,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command. Note that
diff --git a/lisp/info.el b/lisp/info.el
index 51e9eb72edf..c0e342a62d6 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,52 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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 should match the pattern (MANUALS
+. URL-SPEC). MANUALS represents the name of one or many 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 with 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 string.
+
+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."
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1853,45 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return a URL for NODE. NODE should be a string of the form
+\"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (mapconcat (lambda (ch)
- (if (or (< ch 32) ; ^@^A-^Z^[^\^]^^^-
+ (error "Invalid node-name %s" node))
+ ;; use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (char-to-string ch)))
+ node ""))))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'")))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals.
2023-12-07 17:02 ` Eli Zaretskii
@ 2023-12-09 4:05 ` Richard Stallman
0 siblings, 0 replies; 23+ messages in thread
From: Richard Stallman @ 2023-12-09 4:05 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: mekeor, 67615
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> I think each GNU project uses slightly different arrangements. Also,
> how exactly the HTML manuals are arranged on gnu.org is up to the
> projects, not gnu.org admmins (which just provide technical support).
> In any case, this is not the right place to talk about GNU-wide
> conventions and decisions.
We could adopt a standard for this, if that would make it possible
to integrate finding more manuals. I suggest people work on designing
a standard to propose, then send it to gnu-prog-discuss@gnu.org.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-08 0:15 ` bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs Mekeor Melire
@ 2023-12-09 9:42 ` Eli Zaretskii
2023-12-09 11:21 ` Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2023-12-09 9:42 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Fri, 08 Dec 2023 00:15:15 +0000
>
> >From 1e9b31174ab4cfb2edb73f23aa1a3ec86943ba42 Mon Sep 17 00:00:00 2001
> From: Mekeor Melire <mekeor@posteo.de>
> Date: Mon, 4 Dec 2023 16:37:37 +0100
> Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
> to URLs.
Thanks, a few comments below.
> diff --git a/ChangeLog.4 b/ChangeLog.4
> index 24afabdbbb1..0aabd9f52bb 100644
> --- a/ChangeLog.4
> +++ b/ChangeLog.4
> @@ -1,3 +1,11 @@
> +2023-12-08 Mekeor Melire <mekeor@posteo.de>
> +
> + Support online-browsing all Emacs-contained manuals or any other.
> +
> + * lisp/info.el (Info-url-alist): New defcustom that maps
> + manual-names to URL-specifications.
> + (Info-url-for-node): Use it.
> +
This is an auto-generated file, so no need to patch it by hand.
> +*** New user option 'Info-url-alist'.
> +This user option associates manual-names with URLs. It affects the
^^
Our convention is to leave two spaces between sentences.
> +'Info-goto-node-web' command. By default, associations for all
> +Emacs-included manuals are set. Further associations can be added for
> +arbitrary info manuals.
^^^^
"Info", capitalized.
> +(defcustom Info-url-alist
> + '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
> + "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
> + "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
> + "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
> + "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
> + "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
> + "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
> + "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
> + "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
> + "vip" "viper" "vtable" "widget" "wisent" "woman") .
> + "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 should match the pattern (MANUALS
> +. URL-SPEC).
Our style is to say
Each element of this list should have the form (MANUALs . URL-SPEC)
> MANUALS represents the name of one or many manuals.
^^^^^^^^^^^
"one or more"
> +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 string.
^^^^^^^^^
"as a string"
> + :type '(alist
> + :tag "Mapping from manual-name(s) to URL-specification"
> + :key-type (choice
> + (string :tag "A single manual-name")
> + (repeat :tag "List of manual-names" string))
> + :value-type (choice
> + (string :tag "URL-specification string")
> + (function
> + :tag "URL-specification function"))))
Each defcustom should have the :version tag.
> (defun Info-url-for-node (node)
> - "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
> -NODE should be a string on the form \"(manual)Node\". Only emacs
> -and elisp manuals are supported."
> + "Return a URL for NODE. NODE should be a string of the form
> +\"(manual)Node\"."
The first line of a doc string should be a single complete sentence.
This is important because apropos commands show only the first line of
each doc string.
> + ;; use `if-let*' instead of `let*' so we check if an association was
> + ;; found.
Comments should be preferably complete sentences, starting with a
capitalized letter and ending with a period.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-09 9:42 ` Eli Zaretskii
@ 2023-12-09 11:21 ` Mekeor Melire
2023-12-19 23:08 ` bug#67615: [PATCH v4] " Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-09 11:21 UTC (permalink / raw)
To: 67615; +Cc: Eli Zaretskii
[-- Attachment #1: Type: text/plain, Size: 147 bytes --]
2023-12-09 11:42 eliz@gnu.org:
> Thanks, a few comments below.
Thanks for reviewing. I implemented the requested changes. Here's the
new patch:
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-info.el-Info-url-alist-New-option-mapping-manua.patch --]
[-- Type: text/x-patch, Size: 6930 bytes --]
From a30f11d1112a08a32f3da7adce37d8e09b390041 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
to URLs.
---
etc/NEWS | 9 +++++
lisp/info.el | 102 ++++++++++++++++++++++++++++++++++++++++-----------
2 files changed, 90 insertions(+), 21 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..cd1d3b1c060 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -356,6 +356,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary Info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command. Note that
diff --git a/lisp/info.el b/lisp/info.el
index 51e9eb72edf..4ee62c1e729 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,53 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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 should have 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 with 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.
+
+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."
+ :version "30.1"
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1854,46 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return the URL corresponding to NODE.
+
+NODE should be a string of the form \"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (mapconcat (lambda (ch)
- (if (or (< ch 32) ; ^@^A-^Z^[^\^]^^^-
+ (error "Invalid node-name %s" node))
+ ;; Use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (char-to-string ch)))
+ node ""))))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'")))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v4] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-09 11:21 ` Mekeor Melire
@ 2023-12-19 23:08 ` Mekeor Melire
2023-12-23 10:05 ` Eli Zaretskii
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2023-12-19 23:08 UTC (permalink / raw)
To: 67615; +Cc: Eli Zaretskii
[-- Attachment #1: Type: text/plain, Size: 362 bytes --]
Hello again :)
Firstly, I'm happy to announce that my FSF-copyright-assignment is done.
Secondly, I'd like to re-share the same version of the patch from my
last e-mail. Perhaps it was forgotten, perhaps because I did not choose
a new subject line. (I did so for this e-mail.) So here it is again. I'd
appreciate a review or even a commit/merge if it's done.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-info.el-Info-url-alist-New-option-mapping-manua.patch --]
[-- Type: text/x-patch, Size: 6930 bytes --]
From a30f11d1112a08a32f3da7adce37d8e09b390041 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
to URLs.
---
etc/NEWS | 9 +++++
lisp/info.el | 102 ++++++++++++++++++++++++++++++++++++++++-----------
2 files changed, 90 insertions(+), 21 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..cd1d3b1c060 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -356,6 +356,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary Info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command. Note that
diff --git a/lisp/info.el b/lisp/info.el
index 51e9eb72edf..4ee62c1e729 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,53 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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 should have 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 with 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.
+
+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."
+ :version "30.1"
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1854,46 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return the URL corresponding to NODE.
+
+NODE should be a string of the form \"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (mapconcat (lambda (ch)
- (if (or (< ch 32) ; ^@^A-^Z^[^\^]^^^-
+ (error "Invalid node-name %s" node))
+ ;; Use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (char-to-string ch)))
+ node ""))))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'")))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v4] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-19 23:08 ` bug#67615: [PATCH v4] " Mekeor Melire
@ 2023-12-23 10:05 ` Eli Zaretskii
2024-01-08 21:56 ` bug#67615: [PATCH v5] " Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2023-12-23 10:05 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Tue, 19 Dec 2023 23:08:29 +0000
>
> Secondly, I'd like to re-share the same version of the patch from my
> last e-mail. Perhaps it was forgotten, perhaps because I did not choose
> a new subject line.
It wasn't forgotten, but thanks anyway.
I have a few minor comments to this version:
> +(defcustom Info-url-alist
> + '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
> + "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
> + "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
> + "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
> + "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
> + "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
> + "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
> + "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
> + "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
> + "vip" "viper" "vtable" "widget" "wisent" "woman") .
> + "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 should have the form (MANUALs
> +. URL-SPEC). MANUALS represents the name of one or more manuals.
Please reformat/refill this so that "(MANUALs . URL-SPEC)" is not
broken between two lines.
> + (if-let* ((manual (match-string 1 node))
> + (node (match-string 2 node))
> + (association (seq-find
> + (lambda (pair)
> + (seq-contains (ensure-list (car pair))
^^^^^^^^^^^^^
This triggers a byte-compiler warning:
In Info-url-for-node:
info.el:1868:32: Warning: `seq-contains' is an obsolete function (as of 27.1); use `seq-contains-p' instead.
> + (error "No URL-specification associated with manual-name `%s'")))
And this line triggers the following byte-compiler warning:
info.el:1896:6: Warning: `error' called with 0 args to fill 1 format field(s)
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v5] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2023-12-23 10:05 ` Eli Zaretskii
@ 2024-01-08 21:56 ` Mekeor Melire
2024-01-13 9:51 ` Eli Zaretskii
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2024-01-08 21:56 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 67615
[-- Attachment #1: Type: text/plain, Size: 446 bytes --]
2023-12-23 12:05 eliz@gnu.org:
> It wasn't forgotten, but thanks anyway.
> I have a few minor comments to this version
Thanks for...
- not forgetting,
- for all the patience, and
- the comments.
Attached is a new version of the patch which includes the requested
improvements:
- In a docstring, do not break line within form specification.
- Pass a previously missing argument to `error'.
- Use `seq-contains-p' instead of `seq-contains'.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-info.el-Info-url-alist-New-option-mapping-manua.patch --]
[-- Type: text/x-patch, Size: 6927 bytes --]
From 438c259a23e9f6ed6f8c3c460e6856404bfe002d Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
to URLs.
---
etc/NEWS | 9 +++++
lisp/info.el | 103 ++++++++++++++++++++++++++++++++++++++++-----------
2 files changed, 91 insertions(+), 21 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index a6b0beb6ee5..f0540df95f7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -402,6 +402,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary Info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command.
diff --git a/lisp/info.el b/lisp/info.el
index 39ca88c358c..1edf663f9b3 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,53 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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 with 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.
+
+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."
+ :version "30.1"
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1854,47 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return the URL corresponding to NODE.
+
+NODE should be a string of the form \"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (mapconcat (lambda (ch)
- (if (or (< ch 32) ; ^@^A-^Z^[^\^]^^^-
+ (error "Invalid node-name %s" node))
+ ;; Use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains-p (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (char-to-string ch)))
+ node ""))))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'"
+ manual)))
(defvar Info-read-node-completion-table)
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v5] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
2024-01-08 21:56 ` bug#67615: [PATCH v5] " Mekeor Melire
@ 2024-01-13 9:51 ` Eli Zaretskii
2024-01-20 0:50 ` bug#67615: [PATCH v6] Add option Info-url-alist Mekeor Melire
0 siblings, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2024-01-13 9:51 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: 67615@debbugs.gnu.org
> Date: Mon, 08 Jan 2024 21:56:03 +0000
>
> > It wasn't forgotten, but thanks anyway.
>
> > I have a few minor comments to this version
>
> Thanks for...
>
> - not forgetting,
> - for all the patience, and
> - the comments.
>
> Attached is a new version of the patch which includes the requested
> improvements:
>
> - In a docstring, do not break line within form specification.
> - Pass a previously missing argument to `error'.
> - Use `seq-contains-p' instead of `seq-contains'.
Thanks. I was going to install this, but it causes info-tests in the
test suite to fail:
Test test-info-urls backtrace:
signal(ert-test-failed (((should (equal (Info-url-for-node "(emacs)M
ert-fail(((should (equal (Info-url-for-node "(emacs)Minibuffer") "ht
(if (unwind-protect (setq value-2 (apply fn-0 args-1)) (setq form-de
(let (form-description-4) (if (unwind-protect (setq value-2 (apply f
(let ((value-2 'ert-form-evaluation-aborted-3)) (let (form-descripti
(let* ((fn-0 #'equal) (args-1 (condition-case err (list (Info-url-fo
(closure (t) nil (let* ((fn-0 #'equal) (args-1 (condition-case err (
#f(compiled-function () #<bytecode 0x122f3388eba94dc5>)()
handler-bind-1(#f(compiled-function () #<bytecode 0x122f3388eba94dc5
ert--run-test-internal(#s(ert--test-execution-info :test #s(ert-test
ert-run-test(#s(ert-test :name test-info-urls :documentation nil :bo
ert-run-or-rerun-test(#s(ert--stats :selector (not (or ... ...)) :te
ert-run-tests((not (or (tag :unstable) (tag :nativecomp))) #f(compil
ert-run-tests-batch((not (or (tag :unstable) (tag :nativecomp))))
ert-run-tests-batch-and-exit((not (or (tag :unstable) (tag :nativeco
eval((ert-run-tests-batch-and-exit '(not (or (tag :unstable) (tag :n
command-line-1(("-L" ";." "-l" "ert" "-l" "lisp/info-tests.el" "--ev
command-line()
normal-top-level()
Test test-info-urls condition:
(ert-test-failed
((should
(equal (Info-url-for-node "(emacs)Minibuffer")
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html"))
:form
(equal
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer"
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html")
:value nil :explanation
(arrays-of-different-length 68 73
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer"
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html"
first-mismatch-at 68)))
FAILED 1/1 test-info-urls (0.187500 sec) at lisp/info-tests.el:30
If we want the result to include the "html" extension (which might not
be correct, since perhaps we could have Minibuffer.htm?), then please
update the test. Otherwise, it sounds like the code needs some
adjustment to behave as before?
> Subject: [PATCH] * lisp/info.el (Info-url-alist): New option mapping manuals
> to URLs.
Please also improve the commit log message to mention all the changes,
not just the new option. See CONTRIBUTE for details, and you can use
"git log" to see many examples of how we do that.
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v6] Add option Info-url-alist
2024-01-13 9:51 ` Eli Zaretskii
@ 2024-01-20 0:50 ` Mekeor Melire
2024-01-20 1:41 ` Orhan Kemal Yüksel
2024-01-20 7:23 ` Eli Zaretskii
0 siblings, 2 replies; 23+ messages in thread
From: Mekeor Melire @ 2024-01-20 0:50 UTC (permalink / raw)
To: 67615; +Cc: Eli Zaretskii
[-- Attachment #1: Type: text/plain, Size: 1406 bytes --]
2024-01-13 11:51 eliz@gnu.org:
> > From: Mekeor Melire <mekeor@posteo.de>
> > Cc: 67615@debbugs.gnu.org
> > Date: Mon, 08 Jan 2024 21:56:03 +0000
> I was going to install this, but it causes info-tests in the test
> suite to fail:
> If we want the result to include the "html" extension (which might not
> be correct, since perhaps we could have Minibuffer.htm?), then please
> update the test. Otherwise, it sounds like the code needs some
> adjustment to behave as before?
I vote for keeping the ".html" suffix because I can imagine that Texinfo
creates only files with that suffix and it's depends on the web-server
and its configuration if the file is also served when the suffix is
missed in the URL.
Unfortunately, I was not able to verify this in the Texinfo
documentation or source code.
I had to make another adjustment info-test.el to make the test succeed:
Previously, Info-node-for-url failed when the passed manual-name was
neither "emacs" nor "elisp". In particular, it failed for "gnus". Now
that "gnus" is a handled manual-name, it succeeds. But it should still
error when the manual-name is not handled (by the default value of the
newly introduced Info-url-alist).
> Please also improve the commit log message to mention all the changes,
> not just the new option. See CONTRIBUTE for details, and you can use
> "git log" to see many examples of how we do that.
I gave my best.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-option-Info-url-alist.patch --]
[-- Type: text/x-patch, Size: 8323 bytes --]
From 1e75f8397fb6396b2244e87d5a66062c8a11ee16 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] Add option Info-url-alist
* lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
(Info-url-for-node): Use it.
* test/lisp/info-tests.el (test-info-urls): Info-url-for-node should
error when manual-name is not handled in Info-url-alist.
* etc/NEWS: Announce the change.
---
etc/NEWS | 9 ++++
lisp/info.el | 113 +++++++++++++++++++++++++++++++---------
test/lisp/info-tests.el | 4 +-
3 files changed, 100 insertions(+), 26 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index a6b0beb6ee5..f0540df95f7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -402,6 +402,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary Info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command.
diff --git a/lisp/info.el b/lisp/info.el
index 39ca88c358c..78512d0d518 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,53 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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 with 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.
+
+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."
+ :version "30.1"
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1854,49 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
+ "Return the URL corresponding to NODE.
+
+NODE should be a string of the form \"(manual)Node\"."
(unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
+ (error "Invalid node-name %s" node))
+ ;; Use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains-p (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (encoded-node
+ ;; Reproduce GNU Texinfo's way of URL-encoding.
+ ;; (info "(texinfo) HTML Xref Node Name Expansion")
+ (if (equal node "Top")
+ ""
(concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (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 "")))
+ ".html"))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'"
+ manual)))
(defvar Info-read-node-completion-table)
diff --git a/test/lisp/info-tests.el b/test/lisp/info-tests.el
index ebe718167bf..b4f94b77030 100644
--- a/test/lisp/info-tests.el
+++ b/test/lisp/info-tests.el
@@ -34,6 +34,8 @@ test-info-urls
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer-File.html"))
(should (equal (Info-url-for-node "(elisp)Backups and Auto-Saving")
"https://www.gnu.org/software/emacs/manual/html_node/elisp/Backups-and-Auto_002dSaving.html"))
- (should-error (Info-url-for-node "(gnus)Minibuffer File")))
+ (should (equal (Info-url-for-node "(gnus)Don't Panic")
+ "https://www.gnu.org/software/emacs/manual/html_node/gnus/Don_0027t-Panic.html"))
+ (should-error (Info-url-for-node "(nonexistent)Example")))
;;; info-tests.el ends here
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v6] Add option Info-url-alist
2024-01-20 0:50 ` bug#67615: [PATCH v6] Add option Info-url-alist Mekeor Melire
@ 2024-01-20 1:41 ` Orhan Kemal Yüksel
2024-01-20 7:23 ` Eli Zaretskii
1 sibling, 0 replies; 23+ messages in thread
From: Orhan Kemal Yüksel @ 2024-01-20 1:41 UTC (permalink / raw)
To: 67615; +Cc: eliz
[-- Attachment #1: Type: text/plain, Size: 1919 bytes --]
On January 20, 2024 1:50:22 AM GMT+01:00, Mekeor Melire <mekeor@posteo.de> wrote:
>2024-01-13 11:51 eliz@gnu.org:
>
>> > From: Mekeor Melire <mekeor@posteo.de>
>> > Cc: 67615@debbugs.gnu.org
>> > Date: Mon, 08 Jan 2024 21:56:03 +0000
>
>> I was going to install this, but it causes info-tests in the test
>> suite to fail:
>
>> If we want the result to include the "html" extension (which might not
>> be correct, since perhaps we could have Minibuffer.htm?), then please
>> update the test. Otherwise, it sounds like the code needs some
>> adjustment to behave as before?
>
>I vote for keeping the ".html" suffix because I can imagine that Texinfo
>creates only files with that suffix and it's depends on the web-server
>and its configuration if the file is also served when the suffix is
>missed in the URL.
>
>Unfortunately, I was not able to verify this in the Texinfo
>documentation or source code.
>
>I had to make another adjustment info-test.el to make the test succeed:
>Previously, Info-node-for-url failed when the passed manual-name was
>neither "emacs" nor "elisp". In particular, it failed for "gnus". Now
>that "gnus" is a handled manual-name, it succeeds. But it should still
>error when the manual-name is not handled (by the default value of the
>newly introduced Info-url-alist).
>
>> Please also improve the commit log message to mention all the changes,
>> not just the new option. See CONTRIBUTE for details, and you can use
>> "git log" to see many examples of how we do that.
>
>I gave my best.
>
I will send another version of the patch. The %e provided to URL-SPECs in Info-url-alist should not contain the ".html"-suffix. Since we know that the webserver of gnu.org does serve the docs even if the URL omits the HTML-suffix, we should prefer that shorter version since it's easier on the eyes (and better e.g. for IRC etc.).
Sorry for the noise.
[-- Attachment #2: Type: text/html, Size: 3093 bytes --]
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v6] Add option Info-url-alist
2024-01-20 0:50 ` bug#67615: [PATCH v6] Add option Info-url-alist Mekeor Melire
2024-01-20 1:41 ` Orhan Kemal Yüksel
@ 2024-01-20 7:23 ` Eli Zaretskii
2024-01-21 1:43 ` bug#67615: [PATCH v7] " Mekeor Melire
1 sibling, 1 reply; 23+ messages in thread
From: Eli Zaretskii @ 2024-01-20 7:23 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sat, 20 Jan 2024 00:50:22 +0000
>
> > I was going to install this, but it causes info-tests in the test
> > suite to fail:
>
> > If we want the result to include the "html" extension (which might not
> > be correct, since perhaps we could have Minibuffer.htm?), then please
> > update the test. Otherwise, it sounds like the code needs some
> > adjustment to behave as before?
>
> I vote for keeping the ".html" suffix because I can imagine that Texinfo
> creates only files with that suffix and it's depends on the web-server
> and its configuration if the file is also served when the suffix is
> missed in the URL.
What about the case where the HTML docs are produced with one file per
node? doesn't Texinfo create in that case directories that are named
like the manual, but without the .html extension?
^ permalink raw reply [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v7] Add option Info-url-alist
2024-01-20 7:23 ` Eli Zaretskii
@ 2024-01-21 1:43 ` Mekeor Melire
2024-01-27 10:21 ` Eli Zaretskii
0 siblings, 1 reply; 23+ messages in thread
From: Mekeor Melire @ 2024-01-21 1:43 UTC (permalink / raw)
To: 67615; +Cc: Eli Zaretskii
[-- Attachment #1: Type: text/plain, Size: 1482 bytes --]
2024-01-20 09:23 eliz@gnu.org:
> What about the case where the HTML docs are produced with one file per
> node? doesn't Texinfo create in that case directories that are named
> like the manual, but without the .html extension?
I tested this and found out that Texinfo does not create directories for
each node in that case.
The reason why after omitting the .html-suffix gnu.org still serves the
html-manual is its web-server configuration. This was confirmed to me
via IRC in the #gnu channel on libera.chat server.
Attached is a new version of that patch with following changes:
- Let Info-url-for-node skip whitespace and newlines between closing
parenthesis and node-name. This mimics Texinfo as can be traced here:
https://git.savannah.gnu.org/cgit/texinfo.git/tree/info/info.h?h=114e10b2a1cb5ee07ae6b9d1228d6d016c9f86e6#n44
https://git.savannah.gnu.org/cgit/texinfo.git/tree/info/scan.c?h=114e10b2a1cb5ee07ae6b9d1228d6d016c9f86e6#n123
It also makes Info-url-for-node work with the string that is put into
kill-ring with the Info-copy-current-node-name command which uses a
whitespace.
- Do not use a .html suffix, neither in the default value for the new
Info-url-alist, nor in the %e format-thing that can be in user-defined
values of it. Users still can add a ".html" suffix themselves, if the
respective web-server does not support omitting it.
- More tests, including manuals in all relevant directories and formats
and "special" characters.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-option-Info-url-alist.patch --]
[-- Type: text/x-patch, Size: 9077 bytes --]
From 856ea96868c54af8649cd604b5f92cf5cab4ca3c Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Mon, 4 Dec 2023 16:37:37 +0100
Subject: [PATCH] Add option Info-url-alist
* lisp/info.el (Info-url-alist): New option mapping manuals to URLs.
(Info-url-for-node): Use it.
* test/lisp/info-tests.el (test-info-urls): Add more tests. In
particular, Info-url-for-node should error when manual-name is not
handled in Info-url-alist.
* etc/NEWS: Announce the change.
---
etc/NEWS | 9 ++++
lisp/info.el | 108 ++++++++++++++++++++++++++++++++--------
test/lisp/info-tests.el | 14 ++++--
3 files changed, 105 insertions(+), 26 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index a6b0beb6ee5..f0540df95f7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -402,6 +402,15 @@ respectively, in addition to the existing translations 'C-x 8 / e' and
\f
* Changes in Specialized Modes and Packages in Emacs 30.1
+** Info
+
+---
+*** New user option 'Info-url-alist'.
+This user option associates manual-names with URLs. It affects the
+'Info-goto-node-web' command. By default, associations for all
+Emacs-included manuals are set. Further associations can be added for
+arbitrary Info manuals.
+
+++
** New command 'lldb'.
Run the LLDB debugger, analogous to the 'gud-gdb' command.
diff --git a/lisp/info.el b/lisp/info.el
index 39ca88c358c..4b3df1b98a1 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -213,6 +213,53 @@ Info-additional-directory-list
These directories are searched after those in `Info-directory-list'."
:type '(repeat directory))
+(defcustom Info-url-alist
+ '((("auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
+ "ebrowse" "ede" "ediff" "edt" "efaq" "efaq-w32" "eglot" "eieio"
+ "eintr" "elisp" "emacs" "emacs-gnutls" "emacs-mime" "epa" "erc"
+ "ert" "eshell" "eudc" "eww" "flymake" "forms" "gnus"
+ "htmlfontify" "idlwave" "ido" "info" "mairix-el" "message"
+ "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode"
+ "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc"
+ "semantic" "ses" "sieve" "smtpmail" "speedbar" "srecode"
+ "todo-mode" "tramp" "transient" "url" "use-package" "vhdl-mode"
+ "vip" "viper" "vtable" "widget" "wisent" "woman") .
+ "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.
+
+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."
+ :version "30.1"
+ :type '(alist
+ :tag "Mapping from manual-name(s) to URL-specification"
+ :key-type (choice
+ (string :tag "A single manual-name")
+ (repeat :tag "List of manual-names" string))
+ :value-type (choice
+ (string :tag "URL-specification string")
+ (function
+ :tag "URL-specification function"))))
+
(defcustom Info-scroll-prefer-subnodes nil
"If non-nil, \\<Info-mode-map>\\[Info-scroll-up] in a menu visits subnodes.
@@ -1807,33 +1854,50 @@ Info-goto-node-web
(Info-url-for-node (format "(%s)%s" filename node)))))
(defun Info-url-for-node (node)
- "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
-NODE should be a string on the form \"(manual)Node\". Only emacs
-and elisp manuals are supported."
- (unless (string-match "\\`(\\(.+\\))\\(.+\\)\\'" node)
- (error "Invalid node name %s" node))
- (let ((manual (match-string 1 node))
- (node (match-string 2 node)))
- (unless (member manual '("emacs" "elisp"))
- (error "Only emacs/elisp manuals are supported"))
- ;; Encode a bunch of characters the way that makeinfo does.
- (setq node
- (mapconcat (lambda (ch)
- (if (or (< ch 32) ; ^@^A-^Z^[^\^]^^^-
+ "Return the URL corresponding to NODE.
+
+NODE should be a string of the form \"(manual)Node\"."
+ ;; GNU Texinfo skips whitespaces and newlines between the closing
+ ;; parenthesis and the node-name, i.e. space, tab, line feed and
+ ;; carriage return.
+ (unless (string-match "\\`(\\(.+\\))[ \t\n\r]*\\(.+\\)\\'" node)
+ (error "Invalid node-name %s" node))
+ ;; Use `if-let*' instead of `let*' so we check if an association was
+ ;; found.
+ (if-let* ((manual (match-string 1 node))
+ (node (match-string 2 node))
+ (association (seq-find
+ (lambda (pair)
+ (seq-contains-p (ensure-list (car pair))
+ manual #'string-equal-ignore-case))
+ Info-url-alist))
+ (url-spec (cdr association))
+ (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
- ""))
- (concat "https://www.gnu.org/software/emacs/manual/html_node/"
- manual "/"
- (and (not (equal node "Top"))
- (concat
- (url-hexify-string (string-replace " " "-" node))
- ".html")))))
+ (char-to-string ch)))
+ node ""))))))
+ (cond
+ ((stringp url-spec)
+ (format-spec url-spec
+ `((?m . ,manual) (?n . ,node) (?e . ,encoded-node))))
+ ((functionp url-spec)
+ (funcall url-spec manual node encoded-node))
+ (t (error "URL-specification neither string nor function")))
+ (error "No URL-specification associated with manual-name `%s'"
+ manual)))
(defvar Info-read-node-completion-table)
diff --git a/test/lisp/info-tests.el b/test/lisp/info-tests.el
index ebe718167bf..0dfdbf417e8 100644
--- a/test/lisp/info-tests.el
+++ b/test/lisp/info-tests.el
@@ -29,11 +29,17 @@
(ert-deftest test-info-urls ()
(should (equal (Info-url-for-node "(emacs)Minibuffer")
- "https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html"))
+ "https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer"))
(should (equal (Info-url-for-node "(emacs)Minibuffer File")
- "https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer-File.html"))
+ "https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer-File"))
(should (equal (Info-url-for-node "(elisp)Backups and Auto-Saving")
- "https://www.gnu.org/software/emacs/manual/html_node/elisp/Backups-and-Auto_002dSaving.html"))
- (should-error (Info-url-for-node "(gnus)Minibuffer File")))
+ "https://www.gnu.org/software/emacs/manual/html_node/elisp/Backups-and-Auto_002dSaving"))
+ (should (equal (Info-url-for-node "(eintr)car & cdr")
+ "https://www.gnu.org/software/emacs/manual/html_node/eintr/car-_0026-cdr"))
+ (should (equal (Info-url-for-node "(emacs-mime)\tIndex")
+ "https://www.gnu.org/software/emacs/manual/html_node/emacs-mime/Index"))
+ (should (equal (Info-url-for-node "(gnus) Don't Panic")
+ "https://www.gnu.org/software/emacs/manual/html_node/gnus/Don_0027t-Panic"))
+ (should-error (Info-url-for-node "(nonexistent)Example")))
;;; info-tests.el ends here
--
2.41.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* bug#67615: [PATCH v7] Add option Info-url-alist
2024-01-21 1:43 ` bug#67615: [PATCH v7] " Mekeor Melire
@ 2024-01-27 10:21 ` Eli Zaretskii
0 siblings, 0 replies; 23+ messages in thread
From: Eli Zaretskii @ 2024-01-27 10:21 UTC (permalink / raw)
To: Mekeor Melire; +Cc: 67615-done
> From: Mekeor Melire <mekeor@posteo.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 21 Jan 2024 01:43:04 +0000
>
> 2024-01-20 09:23 eliz@gnu.org:
>
> > What about the case where the HTML docs are produced with one file per
> > node? doesn't Texinfo create in that case directories that are named
> > like the manual, but without the .html extension?
>
> I tested this and found out that Texinfo does not create directories for
> each node in that case.
>
> The reason why after omitting the .html-suffix gnu.org still serves the
> html-manual is its web-server configuration. This was confirmed to me
> via IRC in the #gnu channel on libera.chat server.
>
> Attached is a new version of that patch with following changes:
>
> - Let Info-url-for-node skip whitespace and newlines between closing
> parenthesis and node-name. This mimics Texinfo as can be traced here:
>
> https://git.savannah.gnu.org/cgit/texinfo.git/tree/info/info.h?h=114e10b2a1cb5ee07ae6b9d1228d6d016c9f86e6#n44
> https://git.savannah.gnu.org/cgit/texinfo.git/tree/info/scan.c?h=114e10b2a1cb5ee07ae6b9d1228d6d016c9f86e6#n123
>
> It also makes Info-url-for-node work with the string that is put into
> kill-ring with the Info-copy-current-node-name command which uses a
> whitespace.
>
> - Do not use a .html suffix, neither in the default value for the new
> Info-url-alist, nor in the %e format-thing that can be in user-defined
> values of it. Users still can add a ".html" suffix themselves, if the
> respective web-server does not support omitting it.
>
> - More tests, including manuals in all relevant directories and formats
> and "special" characters.
Thanks, installed on the master branch, and closing the bug.
^ permalink raw reply [flat|nested] 23+ messages in thread
end of thread, other threads:[~2024-01-27 10:21 UTC | newest]
Thread overview: 23+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-12-04 0:04 bug#67615: [PATCH] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Mekeor Melire
2023-12-04 0:30 ` Mekeor Melire
2023-12-04 10:02 ` bug#67615: [PATCH v2] " Mekeor Melire
2023-12-04 15:51 ` Mekeor Melire
2023-12-04 16:24 ` Eli Zaretskii
2023-12-05 1:06 ` bug#67615: Org-Mode story on how I gathered the list of Emacs-contained online-manuals Mekeor Melire
2023-12-07 2:48 ` bug#67615: [PATCH v2] * lisp/info.el (Info-url-for-node): Support all Emacs info manuals Richard Stallman
2023-12-07 7:19 ` Eli Zaretskii
2023-12-07 11:56 ` Mekeor Melire
2023-12-07 17:02 ` Eli Zaretskii
2023-12-09 4:05 ` Richard Stallman
2023-12-08 0:15 ` bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs Mekeor Melire
2023-12-09 9:42 ` Eli Zaretskii
2023-12-09 11:21 ` Mekeor Melire
2023-12-19 23:08 ` bug#67615: [PATCH v4] " Mekeor Melire
2023-12-23 10:05 ` Eli Zaretskii
2024-01-08 21:56 ` bug#67615: [PATCH v5] " Mekeor Melire
2024-01-13 9:51 ` Eli Zaretskii
2024-01-20 0:50 ` bug#67615: [PATCH v6] Add option Info-url-alist Mekeor Melire
2024-01-20 1:41 ` Orhan Kemal Yüksel
2024-01-20 7:23 ` Eli Zaretskii
2024-01-21 1:43 ` bug#67615: [PATCH v7] " Mekeor Melire
2024-01-27 10:21 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).