Subject: Re: bug#75366: [PATCH] Improve the doc of key-valid-p
From: Eli Zaretskii <[email-masked]>
To: Hong Xu <[email-masked]>
Cc: [email-masked]
Date: Sun, 05 Jan 2025 08:35:11 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Hong Xu <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 04 Jan 2025 13:43:23 -0800
> 
> On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii <[email-masked]> 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.