Add support for customization group hyperlinks in doc strings

* lisp/help-mode.el (help-customization-group): New button.
(help-xref-customization-group-regexp): New const.
(help-make-xrefs): Use them to allow making customization group
buttons.

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 8aa225a00c3fcc6c34c21b2f8b2b8f8339a44715..f0eb1079cafa14dd75e3af12819cb30ac18d3769 100644 (file)
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -755,6 +755,14 @@ anchor}.  The Info file name defaults to @samp{emacs}.  For example,
 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
 @end smallexample
 
+To link to a customization group, write the single-quoted name of the
+group, preceded by @samp{customization group} (the first character in
+each word is case-insensitive).  For example,
+
+@smallexample
+See the customization group `whitespace' for details.
+@end smallexample
+
 Finally, to create a hyperlink to URLs, write the single-quoted URL,
 preceded by @samp{URL}.  For example,
 

diff --git a/etc/NEWS b/etc/NEWS
index a7b6d9049224e3e5ba2385727154077704e18aad..ec81541e655fee5cf443340dacdb65b26758b45e 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3442,6 +3442,12 @@ The former is now declared obsolete.
 \f
 * Lisp Changes in Emacs 28.1
 
++++
+*** Doc strings can now link to customization groups.
+Text like "customization group 'whitespace'" will be made into a
+button.  When clicked, it'll take the user to a Custom buffer
+displaying that customization group.
+
 +++
 *** New macro 'with-existing-directory'.
 This macro binds 'default-directory' to some other existing directory

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 87f26651e014b96935844a0dc4a2abaded4304a7..08182b71be8e9bfe90067e86d58921d3411ea2ac 100644 (file)
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -228,6 +228,11 @@ The format is (FUNCTION ARGS...).")
   'help-function #'info
   'help-echo (purecopy "mouse-2, RET: read this Info node"))
 
+(define-button-type 'help-customization-group
+  :supertype 'help-xref
+  'help-function #'customize-group
+  'help-echo (purecopy "mouse-2, RET: display this customization group"))
+
 (define-button-type 'help-url
   :supertype 'help-xref
   'help-function #'browse-url
@@ -437,6 +442,10 @@ when help commands related to multilingual environment (e.g.,
    "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+['`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to an Info node.")
 
+(defconst help-xref-customization-group-regexp
+  (purecopy "\\<[Cc]ustomization[ \t\n]+[Gg]roup[ \t\n]+['`‘]\\([^'’]+\\)['’]")
+  "Regexp matching doc string references to a customization group.")
+
 (defconst help-xref-url-regexp
   (purecopy "\\<[Uu][Rr][Ll][ \t\n]+['`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to a URL.")
@@ -543,6 +552,12 @@ that."
                        (setq data ;; possible newlines if para filled
                              (replace-regexp-in-string "[ \t\n]+" " " data t t)))
                       (help-xref-button 2 'help-info data))))
+                ;; Customization groups.
+                (save-excursion
+                  (while (re-search-forward
+                          help-xref-customization-group-regexp nil t)
+                    (help-xref-button 1 'help-customization-group
+                                      (intern (match-string 1)))))
                 ;; URLs
                 (save-excursion
                   (while (re-search-forward help-xref-url-regexp nil t)