bug#74903: [PATCH] Add function to show table of keys when describing keymap variable

[Mekeor Melire <mekeor@posteo.de>]

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

Tags: patch

It'd be nice if users could opt in to have C-h v some-map RET show a
nice table of key bindings for that keymap.  I wrote a function that can
be added to help-fns-describe-variable-functions so that this happens.

What do you think?

Alternatively, we can also add a key binding to help-mode so that users
can easily "switch" from describe-variable to describe-keymap, e.g. per
"K":

	C-h v message-mode-map RET K


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-function-to-show-table-of-keys-when-describing-k.patch --]
[-- Type: text/patch, Size: 2193 bytes --]

From df0fbd4d61a0d0bebcb050f4f22a5ae4c67d0f65 Mon Sep 17 00:00:00 2001
From: Mekeor Melire <mekeor@posteo.de>
Date: Sun, 15 Dec 2024 23:21:00 +0100
Subject: [PATCH] Add function to show table of keys when describing keymap
 variable

* lisp/help-fns.el (help-fns-keymap-key-bindings): New function possible
member of 'help-fns-describe-variable-functions' that shows a table of
key bindings.
* etc/NEWS: Advertise it.
---
 etc/NEWS         | 12 ++++++++++++
 lisp/help-fns.el | 10 ++++++++++
 2 files changed, 22 insertions(+)

diff --git a/etc/NEWS b/etc/NEWS
index 48546a2d916..9ae50ddb923 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -220,6 +220,18 @@ on the header lines are now these two: the selected window uses
 
 ** In 'customize-face', the "Font family" attribute now supports completion.
 
+** Help
+
++++
+*** New function 'help-fns-keymap-key-bindings'.
+This function inserts into the current buffer a table of key bindings if
+the given argument is a variable with a keymap as value.  If you want
+'describe-variable' ('C-h v') to insert a table of key bindings into
+regular "*Help*" buffers, add the following to your init file:
+
+    (add-hook 'help-fns-describe-function-functions
+              #'help-fns-keymap-key-bindings)
+
 \f
 * Editing Changes in Emacs 31.1
 
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 157ec6b8d61..4ed4c64f3ea 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -563,6 +563,16 @@ find-lisp-object-file-name
 	     (src-file (locate-library file-name t nil 'readable)))
 	(and src-file (file-readable-p src-file) src-file))))))
 
+(defun help-fns-keymap-key-bindings (variable)
+  "Insert table of key bindings of keymap VARIABLE into the current buffer.
+You can add this function to the `help-fns-describe-function-functions'
+hook to show examples of using FUNCTION in *Help* buffers produced by
+\\[describe-function]."
+  (when-let* ((value (symbol-value variable))
+              ((keymapp value)))
+    (with-current-buffer standard-output
+      (help--describe-map-tree value))))
+
 (defun help-fns--key-bindings (function)
   (when (commandp function)
     (let ((pt2 (with-current-buffer standard-output (point)))
-- 
2.47.1