bug#67615: [PATCH v3] * lisp/info.el (Info-url-alist): New option mapping manuals to URLs.

[Eli Zaretskii]

> 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.