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

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

[Mekeor Melire]

[-- 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

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

[Eli Zaretskii]

> From: Mekeor Melire <mekeor@posteo.de>
> Date: Sun, 15 Dec 2024 23:14:15 +0000
> 
> 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

We have "C-h b" and "C-h m" which show the bindings, albeit not by
keymap.  Is that not enough for some reason?

Adding yet another help command related to key bindings needs to be
justified, since we already have at least two with overlapping
functionalities.

What do others think about this?

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

[Robert Pluim]

>>>>> On Mon, 16 Dec 2024 17:57:14 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Mekeor Melire <mekeor@posteo.de>
    >> Date: Sun, 15 Dec 2024 23:14:15 +0000
    >> 
    >> 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

    Eli> We have "C-h b" and "C-h m" which show the bindings, albeit not by
    Eli> keymap.  Is that not enough for some reason?

"C-h b" shows all the bindings split out by major and minor mode
already. I guess we could add the name of the relevant keymap as well,
but the people who need to know the name of the keymap generally know
enough about Emacs to figure it out (eg via "C-h k").

    Eli> Adding yet another help command related to key bindings needs to be
    Eli> justified, since we already have at least two with overlapping
    Eli> functionalities.

    Eli> What do others think about this?

I really donʼt see the need for more functionality here.

Robert
-- 

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

[Mekeor Melire]

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

On December 16, 2024 6:28:58 PM GMT+01:00, Robert Pluim <rpluim@gmail.com> wrote:
>>>>>> On Mon, 16 Dec 2024 17:57:14 +0200, Eli Zaretskii <eliz@gnu.org> said:
>
>    >> From: Mekeor Melire <mekeor@posteo.de>
>    >> Date: Sun, 15 Dec 2024 23:14:15 +0000
>    >> 
>    >> 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
>
>    Eli> We have "C-h b" and "C-h m" which show the bindings, albeit not by
>    Eli> keymap.  Is that not enough for some reason?
>
>"C-h b" shows all the bindings split out by major and minor mode
>already. I guess we could add the name of the relevant keymap as well,
>but the people who need to know the name of the keymap generally know
>enough about Emacs to figure it out (eg via "C-h k").
>
>    Eli> Adding yet another help command related to key bindings needs to be
>    Eli> justified, since we already have at least two with overlapping
>    Eli> functionalities.
>
>    Eli> What do others think about this?
>
>I really donʼt see the need for more functionality here.
>
>Robert
>-- 

I get the impression that you talk about M-x describe-keymap RET which does already exist.

That is not what I proposed. What I proposed is two things:

1. Allow users to opt-in to have C-h v foo-keymap RET show a table of key bindings in addition to the formatting as S-expression. This fits well into the existing help-fns mechanism. The patch I submitted implements a prototype.

2. In help-mode, bind a single-char-key like "K" to a command that will allow users to easily switch from describing a variable as variable to describing it as keymap a la describe-keymap.

I proposed (2.) as an alternative to (1.) but my main proposal is (1.). Both approaches have a similar objection though.


[-- Attachment #2: Type: text/html, Size: 3490 bytes --]