On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii wrote: >> From: Hong Xu >> Date: Sat, 4 Jan 2025 12:37:53 -0800 >> >> * lisp/keymap.el (key-valid-p): Add an function key example. Mention >> 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 ""). For > example, saying that "event may be a key stroke or a menu item" is > inaccurate, because is neither and so is . 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.