bug#34784: 26.1; Doc of pseudofunction key `<timeout>'

[Drew Adams <drew.adams@oracle.com>]

> tags 34784 notabug
> thanks
> 
> > There is apparently a <timeout> function key and a `timeout'
> > function-key event?
> 
> There's no timeout function key, it's an event that CUA invented, a
> symbol, that's all.  See cua-base.el.  Any Lisp program can invent
> events of its liking and then inject those events and bind commands to
> them.

I thought that might be the case.

But according to how the Elisp manual talks about
function keys, "fake function keys", and events this
_is_ a function key: one that corresponds to the
`timeout' "event that CUA invented".  It's not a
function key that exists or is used outside CUA,
perhaps (that I wasn't sure about), but it is a
function key, at least in terms of how the manual
talks about such things.

Anyway, back to the point of this bug report: How
is a user to know this info about `<timeout>',
without digging into the code?

The doc speaks of "_fake_ function keys" for use in
menu items (only).  But the doc really doesn't guide
users when it comes to things like this.  Yes, it
talks, in the doc about events, about function-key
events, saying that the event is represented by the
function-key symbol.

But I don't see where the doc describes the kind of
thing that is happening with `C-c <timeout>'.  And
I don't see how a user would find out what that
function key (and it apparently is a function key
and not a fake function key) does, without digging
into the CUA code.

Maybe CUA needs, itself, to provide some help/doc
for users about this?  Or maybe Emacs can provide
some general mechanism for users to discover what
such an event does/means?

Keys in a key sequence that we present to a user
should be clear - including function keys.  We
document those that are common.  We don't document
`<timeout>'.  At least CUA should document it, I
think.

There should be some way for a user to find out
more about it, when `C-c C-h' shows it.  How does
a user type/use a key sequence such as
`C-c <timeout>'?  How does a user find that out?

Some user help is missing here.  You may have a
different/better idea of what is missing and where
it belongs, but don't you agree that something is
missing in terms of user help here?