bug#75366: [PATCH] Improve the doc of key-valid-p

bug#75366: [PATCH] Improve the doc of key-valid-p

[Hong Xu]

* lisp/keymap.el (key-valid-p): Add an function key example.  Mention
<left> as a cursor control key instead of a function key.  Rename
some "characters" to "key strokes" to be consistent with the terminology
in the first paragraph.  Briefly explain what an event may be.
---
 lisp/keymap.el | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/lisp/keymap.el b/lisp/keymap.el
index 3aed1d4b4cac..e447bf648a10 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -327,21 +327,23 @@ key-valid-p
 with a single space character separating one key stroke from another.
 
 Each key stroke is either a single character, or the name of an
-event, surrounded by angle brackets <like-this>.  In addition, any
-key stroke may be preceded by one or more modifier keys.  Finally,
-a limited number of characters have a special shorthand syntax.
+event, surrounded by angle brackets <like-this>.  An event may be a key
+stroke or a menu item.  In addition, any key stroke may be preceded by
+one or more modifier keys.  Finally, a limited number of key strokes
+have a special shorthand syntax.
 
 Here are some example of valid key sequences.
 
   \"f\"           (the key `f')
+  \"<f6>\"        (the function key named \"F6\")
   \"S o m\"       (a three-key sequence of the keys `S', `o' and `m')
   \"C-c o\"       (a two-key sequence: the key `c' with the control modifier
                  followed by the key `o')
-  \"H-<left>\"    (the function key named \"left\" with the hyper modifier)
+  \"H-<left>\"    (the cursor control key named \"left\" with the hyper modifier)
   \"M-RET\"       (the \"return\" key with a meta modifier)
   \"C-M-<space>\" (the \"space\" key with both the control and meta modifiers)
 
-These are the characters that have special shorthand syntax:
+These key strokes have special shorthand syntax:
 NUL, RET, TAB, LFD, ESC, SPC, DEL.
 
 Modifiers have to be specified in this order:
-- 
2.47.1

bug#75366: [PATCH] Improve the doc of key-valid-p

[Hong Xu]

On 2025-01-04 Sat 12:37 GMT-08, Hong Xu <hong@topbug.net> wrote:

> -  \"H-<left>\"    (the function key named \"left\" with the hyper modifier)
> +  \"H-<left>\"    (the cursor control key named \"left\" with the hyper modifier)

This naming is based on the Wikipedia article "Function Key": https://en.wikipedia.org/wiki/Function_key
(See the first figure in the article)

-- 
Hong

bug#75366: [PATCH] Improve the doc of key-valid-p

[Eli Zaretskii]

> From: Hong Xu <hong@topbug.net>
> Date: Sat,  4 Jan 2025 12:37:53 -0800
> 
> * lisp/keymap.el (key-valid-p): Add an function key example.  Mention
> <left> as a cursor control key instead of a function key.  Rename
> some "characters" to "key strokes" to be consistent with the terminology
> in the first paragraph.  Briefly explain what an event may be.

Thanks, but the changes you suggest to make are not really correct or
at least inaccurate (with the exception of adding "<f6>").  For
example, saying that "event may be a key stroke or a menu item" is
inaccurate, because <mouse-1> is neither and so is <sigusr1>.

What is wrong with the current text that you think it needs these
changes?

> -These are the characters that have special shorthand syntax:
> +These key strokes have special shorthand syntax:
>  NUL, RET, TAB, LFD, ESC, SPC, DEL.

They are all characters, not key strokes.

bug#75366: [PATCH] Improve the doc of key-valid-p

[Hong Xu]

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

On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Hong Xu <hong@topbug.net>
>> Date: Sat,  4 Jan 2025 12:37:53 -0800
>> 
>> * lisp/keymap.el (key-valid-p): Add an function key example.  Mention
>> <left> as a cursor control key instead of a function key.  Rename
>> some "characters" to "key strokes" to be consistent with the terminology
>> in the first paragraph.  Briefly explain what an event may be.
>
> Thanks, but the changes you suggest to make are not really correct or
> at least inaccurate (with the exception of adding "<f6>").  For
> example, saying that "event may be a key stroke or a menu item" is
> inaccurate, because <mouse-1> is neither and so is <sigusr1>.

I attached an updated version to correct the event description.

>
> What is wrong with the current text that you think it needs these
> changes?

The current text reads a bit confusing to me.

The function, based on its name and the current text, gives me an
impression that this is only about key strokes as those on a keyboard.
However, it's actually more than key strokes as those on a keyboard.
(I've added a mouse example in the updated patch to further clarify
this.)

For example, the "Modifying Menus" node (correctly) cites this function
in the context of binding a menu item. The docstring of this function
and the citing text together can confuse a unfamiliar reader quite a
bit.

Perhaps the ultimate confusion point is the name of the function and the
definition of key sequences and key strokes in the docstring, but these
may be harder to change.

>
>> -These are the characters that have special shorthand syntax:
>> +These key strokes have special shorthand syntax:
>>  NUL, RET, TAB, LFD, ESC, SPC, DEL.
>
> They are all characters, not key strokes.

I changed them back to characters in the updated version. But based on
the definition earlier, "each key stroke is either a single character,
or the name of an event...", they are also key strokes.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-Improve-the-doc-of-key-valid-p.patch --]
[-- Type: text/x-patch, Size: 2210 bytes --]

From 73a686feae4327dd23a2d7c350b528ceed5d5119 Mon Sep 17 00:00:00 2001
From: Hong Xu <hong@topbug.net>
Date: Sat, 4 Jan 2025 12:32:24 -0800
Subject: [PATCH v2] Improve the doc of key-valid-p

* lisp/keymap.el (key-valid-p): Add an function key and mouse button
example.  Mention <left> as a cursor control key instead of a function
key.  Briefly explain what an event may be.
---
 lisp/keymap.el | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/lisp/keymap.el b/lisp/keymap.el
index 3aed1d4b4cac..d1ff52ea3974 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -327,21 +327,26 @@ key-valid-p
 with a single space character separating one key stroke from another.
 
 Each key stroke is either a single character, or the name of an
-event, surrounded by angle brackets <like-this>.  In addition, any
-key stroke may be preceded by one or more modifier keys.  Finally,
-a limited number of characters have a special shorthand syntax.
+event, surrounded by angle brackets <like-this>.  An event may be
+pushing a key, clicking on a menu item, pressing a mouse button, etc.
+In addition, any key stroke may be preceded by one or more modifier
+keys.  Finally, a limited number of characters have a special shorthand
+syntax.
 
 Here are some example of valid key sequences.
 
   \"f\"           (the key `f')
+  \"<f6>\"        (the function key named \"F6\")
+  \"<mouse-1>\"   (the mouse button named \"mouse-1\", commonly referred to as
+                 the left button)
   \"S o m\"       (a three-key sequence of the keys `S', `o' and `m')
   \"C-c o\"       (a two-key sequence: the key `c' with the control modifier
                  followed by the key `o')
-  \"H-<left>\"    (the function key named \"left\" with the hyper modifier)
+  \"H-<left>\"    (the cursor control key named \"left\" with the hyper modifier)
   \"M-RET\"       (the \"return\" key with a meta modifier)
   \"C-M-<space>\" (the \"space\" key with both the control and meta modifiers)
 
-These are the characters that have special shorthand syntax:
+These characters have special shorthand syntax:
 NUL, RET, TAB, LFD, ESC, SPC, DEL.
 
 Modifiers have to be specified in this order:
-- 
2.47.1


[-- Attachment #3: Type: text/plain, Size: 11 bytes --]



-- 
Hong

bug#75366: [PATCH] Improve the doc of key-valid-p

[Eli Zaretskii]

> From: Hong Xu <hong@topbug.net>
> Cc: 75366@debbugs.gnu.org
> Date: Sat, 04 Jan 2025 13:43:23 -0800
> 
> On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > What is wrong with the current text that you think it needs these
> > changes?
> 
> The current text reads a bit confusing to me.
> 
> The function, based on its name and the current text, gives me an
> impression that this is only about key strokes as those on a keyboard.
> However, it's actually more than key strokes as those on a keyboard.
> (I've added a mouse example in the updated patch to further clarify
> this.)
> 
> For example, the "Modifying Menus" node (correctly) cites this function
> in the context of binding a menu item. The docstring of this function
> and the citing text together can confuse a unfamiliar reader quite a
> bit.
> 
> Perhaps the ultimate confusion point is the name of the function and the
> definition of key sequences and key strokes in the docstring, but these
> may be harder to change.

Thanks, installed on the emacs-30 branch, and closing the bug.