From b4bf34acaba98ddeae6f97355b67da5d2ac13e91 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 5 Mar 2021 02:49:07 +0100
Subject: [PATCH] Add new option help-link-key-to-documentation

* lisp/help.el (help-link-key-to-documentation): New user option.
(substitute-command-keys): Add 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 36d04aa2d8..acb6c653db 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.
+
 ** image-dired
 
 ---
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d61b1bdc62..53acbf97e7 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -376,6 +376,13 @@ 'help-news
     (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 a5d5037bfe..03c5b8e230 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1058,6 +1058,14 @@ lookup-minor-mode-from-indicator
     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 @@ substitute-command-keys
                         (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].
-- 
2.30.2