master 68d11cc: Add new option help-link-key-to-documentation

[Stefan Kangas]

branch: master
commit 68d11cc248524750c008a418faca4a9182d51758
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    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.
---
 etc/NEWS          |  8 ++++++++
 lisp/help-mode.el |  7 +++++++
 lisp/help.el      | 17 ++++++++++++++++-
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index 602d13e..35bc961 100644
--- 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 d61b1bd..53acbf9 100644
--- 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)))
+
 
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)
diff --git a/lisp/help.el b/lisp/help.el
index a5d5037..510dee7 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1058,6 +1058,14 @@ is currently activated with completion."
     result))
 
 
+(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].