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

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

The table is a bit redundant with the s-exp representation and I'm not
sure we want to spend all this time&space printing out a large keymap,
but maybe we could use the `help-fns-describe-variable-functions`
mechanism to add a one-liner that can be clicked to get to the
keymap-specific description, a bit like Custom vars have a "You can
customize this variable" link.
WDYT?

[ There is also something to be said to spice up `describe-keymap` so it
  can be used to *modify* a keymap.  But that comes with many more
  difficulties (the main one being how to save those modifications so
  they survive a restart).  ]


        Stefan

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

[Mekeor Melire]

I had accidentally sent following email only to Stefan Monnier 
rather than the whole list.  I'm thus sending it again.


On Mon, 16 Dec 2024 22:03:22 -0500, Stefan Monnier 
<monnier@iro.umontreal.ca> said:

> The table is a bit redundant with the s-exp representation and 
> I'm not sure we want to spend all this time&space printing out a 
> large keymap, but maybe we could use the 
> `help-fns-describe-variable-functions` mechanism to add a 
> one-liner that can be clicked to get to the keymap-specific 
> description, a bit like Custom vars have a "You can customize 
> this variable" link.  WDYT?

I agree that there's redundancy.  But since adding the function 
`help-fns-keymap-key-bindings' from my patch to 
`help-fns-describe-variable-functions` would be opt-in, it'd be up 
to the user to decide between redundancy and convenience.

Nevertheless, I like your idea of a clickable button, e.g. worded 
"View this keymap as a table" in the *Help* buffer.  Let me 
continue your comparison to the "You can customize this variable" 
button by noting that its command, `help-customize', is also bound 
to "c" in Help-Mode.  I'd also like a key binding for "View this 
keymap as a table", e.g. "k".  So, these key sequences would 
result in the same state:

    C-h v foo-map RET k
    M-x describe-keymap foo-map RET

But we can build up this idea further: What if these would also 
result in the same state? (`ido-mode' is both a variable and a 
function.)

    C-h f ido-mode RET o
    C-h v ido-mode RET o
    C-h o ido-mode RET

And also:

    C-h v ido-mode RET f
    C-h f ido-mode RET

What do you think about enabling users to easily "effectively switch"
between describe-* commands in this way?

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

[Mekeor Melire]

Resending an email that I mistakenly had only sent to Stefan 
Monnier:


On Mon, 16 Dec 2024 22:03:22 -0500, Stefan Monnier 
<monnier@iro.umontreal.ca> said: 
 
> The table is a bit redundant with the s-exp representation and 
> I'm not sure we want to spend all this time&space printing out a 
> large keymap, but maybe we could use the 
> `help-fns-describe-variable-functions` mechanism to add a 
> one-liner that can be clicked to get to the keymap-specific 
> description, a bit like Custom vars have a "You can customize 
> this variable" link.  WDYT? 
 
I agree that there's redundancy.  But since adding the function 
`help-fns-keymap-key-bindings' from my patch to 
`help-fns-describe-variable-functions` would be opt-in, it'd be up 
to the user to decide between redundancy and convenience. 
Nevertheless, I like your idea of a clickable button, e.g. worded 
"View this keymap as a table" in the *Help* buffer.  Let me 
continue your comparison to the "You can customize this variable" 
button by noting that its command, `help-customize', is also bound 
to "c" in Help-Mode.  I'd also like a key binding for "View this 
keymap as a table", e.g. "k".  So, these key sequences would 
result in the same state:

    C-h v foo-map RET k
    M-x describe-keymap foo-map RET

But we can build up this idea further: What if these would also 
result in the same state? (`ido-mode' is both a variable and a 
function.)

    C-h f ido-mode RET o
    C-h v ido-mode RET o
    C-h o ido-mode RET

And also:

    C-h v ido-mode RET f
    C-h f ido-mode RET

What do you think about enabling users to easily "effectively switch"
between describe-* commands in this way?

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

[Robert Pluim]

>>>>> On Mon, 16 Dec 2024 18:41:19 +0000, Mekeor Melire <mekeor@posteo.de> said:

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

No, Iʼm talking about `describe-bindings'.

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

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

Again, I donʼt see a need for it. A user trying to figure out
keybindings is not going to be inspecting keymap variables, and
`describe-bindings' or `describe-mode' tells them what they need to
know. A developer writing code presumably knows about keymaps, and
doesnʼt need a different visual representation of them to get stuff
done.

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

See my previous paragraph.

Robert
-- 

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

[Juri Linkov]

>     Mekeor> 1. Allow users to opt-in to have C-h v foo-keymap RET show a table of
>     Mekeor> key bindings in addition to the formatting as S-expression. This fits
>     Mekeor> well into the existing help-fns mechanism. The patch I submitted
>     Mekeor> implements a prototype.
>
> Again, I donʼt see a need for it. A user trying to figure out
> keybindings is not going to be inspecting keymap variables, and
> `describe-bindings' or `describe-mode' tells them what they need to
> know. A developer writing code presumably knows about keymaps, and
> doesnʼt need a different visual representation of them to get stuff
> done.

It would be nice if users will be able first to see keymap tables
in the output of `describe-repeat-maps', then click on a map
variable, and see the same keymap table individually.

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

[Robert Pluim]

>>>>> On Tue, 17 Dec 2024 09:59:57 +0200, Juri Linkov <juri@linkov.net> said:

    Mekeor> 1. Allow users to opt-in to have C-h v foo-keymap RET show a table of
    Mekeor> key bindings in addition to the formatting as S-expression. This fits
    Mekeor> well into the existing help-fns mechanism. The patch I submitted
    Mekeor> implements a prototype.
    >> 
    >> Again, I donʼt see a need for it. A user trying to figure out
    >> keybindings is not going to be inspecting keymap variables, and
    >> `describe-bindings' or `describe-mode' tells them what they need to
    >> know. A developer writing code presumably knows about keymaps, and
    >> doesnʼt need a different visual representation of them to get stuff
    >> done.

    Juri> It would be nice if users will be able first to see keymap tables
    Juri> in the output of `describe-repeat-maps', then click on a map
    Juri> variable, and see the same keymap table individually.

? I must be misunderstanding, because thatʼs already how
`describe-repeat-maps' works.

Robert
-- 

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

[Juri Linkov]

>> It would be nice if users will be able first to see keymap tables
>> in the output of `describe-repeat-maps', then click on a map
>> variable, and see the same keymap table individually.
>
> ? I must be misunderstanding, because thatʼs already how
> `describe-repeat-maps' works.

I meant that after clicking on the map variable in the heading
it could show the same keymap.

BTW, I just finally fixed `describe-repeat-maps' to use the very
useful function 'cl--map-keymap-recursively' instead of 'map-keymap'.

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

[Robert Pluim]

>>>>> On Tue, 17 Dec 2024 21:00:11 +0200, Juri Linkov <juri@linkov.net> said:

    >>> It would be nice if users will be able first to see keymap tables
    >>> in the output of `describe-repeat-maps', then click on a map
    >>> variable, and see the same keymap table individually.
    >> 
    >> ? I must be misunderstanding, because thatʼs already how
    >> `describe-repeat-maps' works.

    Juri> I meant that after clicking on the map variable in the heading
    Juri> it could show the same keymap.

Thatʼs just narrowing the buffer, no? 😉

Robert
-- 

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

[Juri Linkov]

>     >>> It would be nice if users will be able first to see keymap tables
>     >>> in the output of `describe-repeat-maps', then click on a map
>     >>> variable, and see the same keymap table individually.
>     >> 
>     >> ? I must be misunderstanding, because thatʼs already how
>     >> `describe-repeat-maps' works.
>
>     Juri> I meant that after clicking on the map variable in the heading
>     Juri> it could show the same keymap.
>
> Thatʼs just narrowing the buffer, no? 😉

Except that it also shows a docstring and a link to source code.

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

It's quite different, since his proposal is about displaying keymap
values held in variables (i.e. not necessarily currently active).

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

AFAICT his proposal does not add any new command (help or other).
What am I missing?


        Stefan

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

[Mekeor Melire]

    Monnier> AFAICT his proposal does not add any new command 
    (help or Monnier> other).  What am I missing?

I think the confusion originates in a misunderstanding between my 
initial mail and Eli's initial response where Eli said:

    Eli> We have "C-h b" and "C-h m" which show the bindings, 
    albeit not Eli> by keymap. 

Most further responses seem to assume that I want to reimplement
`describe-bindings' (C-h b).

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

[Mekeor Melire]

I'd like to close this feature request because maintainers didn't agree
with my vision.  Thank y'all nevertheless.  :)

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

[Eli Zaretskii]

> From: Mekeor Melire <mekeor@posteo.de>
> Date: Tue, 24 Dec 2024 23:19:45 +0000
> 
> I'd like to close this feature request because maintainers didn't agree
> with my vision.  Thank y'all nevertheless.  :)

Thanks, done.