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

[Hong Xu <hong@topbug.net>]

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