bug#81462: [PATCH] Skip non-key events in `where-is-internal' with FIRSTONLY

>> Could you clarify why you think this is a bug?
>> The doc says:
>>
>>     If FIRSTONLY is the symbol ‘non-ascii’, return the first binding
>>     found, no matter what it is.
>
> At the end of the docstring for `where-is-internal', it says:
>
>     Keys that are represented as events that have a ‘non-key-event’ non-nil
>     symbol property are ignored.

I see.  [ I don't think that addition was justified.  ]

> I figured that the intent was that such events in keymaps are not
> really keys, cannot be invoked by users, and therefore should not be
> listed by, e.g., where-is, describe-function, or
> substitute-command-keys.  FWIW, shadowed key bindings are also skipped
> even when FIRSTONLY is `non-ascii', so this seemed like an analogous
> situation to me.

I'd argue they *can* be invoked by users, by causing the
corresponding event.  I think it's not that different from the "events"
used for menu entries.  Or the pseudo-events used for clicks on GUI
elements like `mode-line`, `left-fringe`, ...

I think it's better to "demote" them (i.e. list them further down the
list) rather than completely skip them.

>> BTW, I see that in bug#55940, Lars introduced the property `non-key-event`,
>> but I'm not sure it's been fully thought through.  It seems wrong not to
>> list them at all in `where-is-internal`.  I suspect it should be
>> integrated into `preferred_sequence_p` instead.
> The reason I was looking into this code at all was because I wanted to
> tweak the behavior of where-is at my site.  Apologies in advance for
> the verboseness below.

No apology needed, such background info is very welcome.

> Many of my site's users enable evil-mode, which happens to use some
> non-key events for implementation reasons---see function
> `evil-get-auxiliary-keymap'---and marking these synthetic events with
> the `non-key-event' property might be a reasonable way to prevent
> `substitute-command-keys' from returning them (albeit with some
> additional patching here).
>
> As an example, from emacs -Q -L ~/src/evil-mode:
>
>   (evil-mode)
>   (defun my-custom-command () (interactive))
>   (keymap-global-set "C-x x z" #'my-custom-command) ;global key
> binding for non-evil-mode users
>   (evil-define-key 'normal lisp-interaction-mode-map
>     (kbd "<f4>") #'my-custom-command)
>   (evil-define-key 'insert lisp-interaction-mode-map
>     (kbd "<f5>") #'my-custom-command)
>
> Now, invoking where-is or describe-function on my-custom-command
> (assume you are in evil-normal-state) will tell you that the command
> is bound to:
>
> my-custom-command is on <f4>, <normal-state> <f4>, <insert-state> <f5>, C-x x z
>
> Whereas the only key sequences you can actually type are <f4> and C-x
> x z.  I would like to give the `normal-state' and `insert-state'
> symbols a `non-key-event' property to prevent them from showing up in
> this output at all.

Interesting.  This ties in with the recent discussion on emacs-devel
about the "slow erosion of help's utility" for things like
"metafunctions" (think `indent-for-tab-command`) and packages
like Transient.

I'm thinking of adding what I think we should call "partial bindings"
such that when a key lookup finds such a partial-binding it doesn't stop
but keeps looking further and returns a "composite command" made up of
all the partial bindings found (plus potentially a final non-partial
binding), and partial bindings would have enough extra info to describe
themselves (e.g. describe when they're active and when not).
So `describe-function` could end up saying something like

    my-custom-command is on C-x x z, <f4> (in normal state), <f5>
    (in insert state)


=== Stefan