Re: [External] : Re: Consistent face for keys in *Help* and `substitute-command-keys'

[Stefan Kangas <stefan@marxist.se>]

[-- Attachment #1: Type: text/plain, Size: 839 bytes --]

Juri Linkov <juri@linkov.net> writes:

> It would be nice to keep the current face 'help-key-binding'
> even after adding links.

Yes, as it happens that is exactly what I'm currently experimenting
with.  See the attached patch if you want to try it out; I think the
effect is quite nice.

But I'm seeing bootstrap problems if I flip the new option here to t, so
we couldn't use it as the default in its current form.

[The problem is that the button type `help-function' is defined in
help-mode.el, but that file is not autoloaded (and help.el is).  There
are several ways to fix it, but I haven't yet had time to think about
which is better.  (For example, we could force the option to nil during
bootstrap.  Or we could just move the button definitions into its own
file or into help.el to make sure they are there during bootstrap.) ]

[-- Attachment #2: 0001-Add-new-option-help-link-key-to-documentation.patch --]
[-- Type: text/x-diff, Size: 3243 bytes --]

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)))
+
 \f
 (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))
 
 \f
+(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