From 937e2ed9d7b5a1a43f199c8342ed9ee2aaa7cac8 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 option.
(substitute-command-keys): Add link from keys to the command they
are bound to if above new option is non-nil.  (Bug#8951)
* etc/NEWS: Announce the new option.
---
 etc/NEWS          |  7 +++++++
 lisp/help-mode.el |  7 +++++++
 lisp/help.el      | 14 +++++++++++++-
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index ce337e7517..4c3f2418a3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -928,6 +928,13 @@ be assumed to be a propertized string.
 Note that the new face will also be used in tooltips.  When using the
 GTK toolkit, this is only true if 'x-gtk-use-system-tooltips' is t.
 
+---
+*** 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.  Note that this does not affect listings of key bindings and
+functions.
+
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index c7eaae5feb..7691002f7f 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -321,6 +321,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)
 
diff --git a/lisp/help.el b/lisp/help.el
index 94073e5730..cc624d5737 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -978,6 +978,14 @@ lookup-minor-mode-from-indicator
     result))
 
 
+(defcustom help-link-key-to-documentation nil
+  "Non-nil means to link keys to their command in *Help* buffers.
+This affects \\\\=\\[command] substitutions in documentation
+strings done by `substitute-command-keys'.  "
+  :type 'boolean
+  :version "28.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
@@ -1065,7 +1073,11 @@ 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))
+                                  (help-mode--add-function-link key fun)
+                                key))))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
-- 
2.30.1