GNU bug report logs - #75366
[PATCH] Improve the doc of key-valid-p

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#75366: closed ([PATCH] Improve the doc of key-valid-p)
Date: Sun, 05 Jan 2025 06:36:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Sun, 05 Jan 2025 08:35:11 +0200
with message-id <86ttadahuo.fsf <at> gnu.org>
and subject line Re: bug#75366: [PATCH] Improve the doc of key-valid-p
has caused the debbugs.gnu.org bug report #75366,
regarding [PATCH] Improve the doc of key-valid-p
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
75366: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=75366
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Improve the doc of key-valid-p
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.
---
 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

[Message part 3 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 75366-done <at> debbugs.gnu.org
Subject: Re: bug#75366: [PATCH] Improve the doc of key-valid-p
Date: Sun, 05 Jan 2025 08:35:11 +0200

> From: Hong Xu <hong <at> topbug.net>
> Cc: 75366 <at> debbugs.gnu.org
> Date: Sat, 04 Jan 2025 13:43:23 -0800
> 
> On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii <eliz <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.