Add new option help-link-key-to-documentation

* lisp/help.el (help-link-key-to-documentation): New user option.
(substitute-command-keys): Add a link from keys to the command they
are bound to, if the above new option is non-nil.  (Bug#8951)
* etc/NEWS: Announce the new option.

diff --git a/etc/NEWS b/etc/NEWS
index 602d13eefad8a6f946b1198fcea87d5cea821584..35bc9611a3b7cd1fec591592590d9d276b1a5a69 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -136,6 +136,14 @@ function which returns a string.  For the first two cases, the length
 of the resulting name is controlled by 'eww-buffer-name-length'.  By
 default, no automatic renaming is performed.
 
+** Help
+
+*** New user option 'help-link-key-to-documentation'.
+When this option is non-nil, key bindings displayed in the *Help*
+buffer will be linked to the documentation for the command they are
+bound to.  This does not affect listings of key bindings and
+functions (such as `C-h b').
+
 ** info-look
 
 ---

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d61b1bdc624dc76715f181b3911d42c6a1e62bdb..53acbf97e7d8fd840804f1ded0a665af181e622c 100644 (file)
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -376,6 +376,13 @@ The format is (FUNCTION ARGS...).")
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+;;;###autoload
+(defun help-mode--add-function-link (str fun)
+  (make-text-button (copy-sequence str) nil
+                    'type 'help-function
+                    'help-args (list fun)))
+
 \f
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)

diff --git a/lisp/help.el b/lisp/help.el
index a5d5037bfe023309b366309be180343b8dcac924..510dee7f7ad312baf81f2b67ae5d13c1720936a7 100644 (file)
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1058,6 +1058,14 @@ is currently activated with completion."
     result))
 
 \f
+(defcustom help-link-key-to-documentation t
+  "Non-nil means link keys to their command in *Help* buffers.
+This affects \\\\=\\[command] substitutions in documentation
+strings done by `substitute-command-keys'."
+  :type 'boolean
+  :version "29.1"
+  :group 'help)
+
 (defun substitute-command-keys (string)
   "Substitute key descriptions for command names in STRING.
 Each substring of the form \\\\=[COMMAND] is replaced by either a
@@ -1145,7 +1153,14 @@ Otherwise, return a new string."
                         (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (help--key-description-fontified key)))))
+                    (let ((key (help--key-description-fontified key)))
+                      (insert (if (and help-link-key-to-documentation
+                                       (functionp fun))
+                                  ;; The `fboundp' fixes bootstrap.
+                                  (if (fboundp 'help-mode--add-function-link)
+                                      (help-mode--add-function-link key fun)
+                                    key)
+                                key))))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].