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

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

[Drew Adams]

See https://emacs.stackexchange.com/a/48221/105.

There is apparently a <timeout> function key and a `timeout'
function-key event?  Please consider documenting this in the Elisp
manual.


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Drew Adams]

I meant to use "function key", not "pseudofunction key" in the Bug title.  Forgot to correct that.

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

[Eli Zaretskii]

tags 34784 notabug
thanks

> Date: Thu, 7 Mar 2019 17:27:14 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> See https://emacs.stackexchange.com/a/48221/105.
> 
> 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.

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

[Drew Adams]

> 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?

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 08:52:46 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34784@debbugs.gnu.org
> 
> Anyway, back to the point of this bug report: How
> is a user to know this info about `<timeout>',
> without digging into the code?

Why should they?  This is an internal matter between CUA and itself, a
detail of its implementation.

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

[Drew Adams]

> > Anyway, back to the point of this bug report: How
> > is a user to know this info about `<timeout>',
> > without digging into the code?
> 
> Why should they?  This is an internal matter between CUA and itself, a
> detail of its implementation.

Huh? Why shouldn't they?  If a user sees this help:

 key             binding
 ---             -------
 C-c <timeout>   copy-region-as-kill

and s?he wants to know how to invoke
`copy-region-as-kill' starting with prefix `C-c',
where is s?he supposed to turn for that info?

If this were "an internal matter between CUA and
itself" then `C-c C-h' wouldn't (and shouldn't)
show it to users.

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 09:20:19 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34784@debbugs.gnu.org
> 
> > > Anyway, back to the point of this bug report: How
> > > is a user to know this info about `<timeout>',
> > > without digging into the code?
> > 
> > Why should they?  This is an internal matter between CUA and itself, a
> > detail of its implementation.
> 
> Huh? Why shouldn't they?

Because it's an implementation detail.

> If a user sees this help:
> 
>  key             binding
>  ---             -------
>  C-c <timeout>   copy-region-as-kill
> 
> and s?he wants to know how to invoke
> `copy-region-as-kill' starting with prefix `C-c',
> where is s?he supposed to turn for that info?

To the source code, of course.

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

[Drew Adams]

> > > > Anyway, back to the point of this bug report: How
> > > > is a user to know this info about `<timeout>',
> > > > without digging into the code?
> > >
> > > Why should they?  This is an internal matter between CUA and itself, a
> > > detail of its implementation.
> >
> > Huh? Why shouldn't they?
> 
> Because it's an implementation detail.

How so - what makes you think that?

> > If a user sees this help:
> >
> >  key             binding
> >  ---             -------
> >  C-c <timeout>   copy-region-as-kill
> >
> > and s?he wants to know how to invoke
> > `copy-region-as-kill' starting with prefix `C-c',
> > where is s?he supposed to turn for that info?
> 
> To the source code, of course.

To understand an external, user-visible, external, key
description from `C-h' a user needs to dig into the
source code?  That's a sorry stance for Emacs help to
take, I think.

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 11:39:29 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34784@debbugs.gnu.org
> 
> > > > > Anyway, back to the point of this bug report: How
> > > > > is a user to know this info about `<timeout>',
> > > > > without digging into the code?
> > > >
> > > > Why should they?  This is an internal matter between CUA and itself, a
> > > > detail of its implementation.
> > >
> > > Huh? Why shouldn't they?
> > 
> > Because it's an implementation detail.
> 
> How so - what makes you think that?

Because I've read the code.

> > > and s?he wants to know how to invoke
> > > `copy-region-as-kill' starting with prefix `C-c',
> > > where is s?he supposed to turn for that info?
> > 
> > To the source code, of course.
> 
> To understand an external, user-visible, external, key
> description from `C-h' a user needs to dig into the
> source code?  That's a sorry stance for Emacs help to
> take, I think.

No, it's just a (mildly unfortunate) consequence of the fact that
internal details are visible in user-level commands.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> tags 34784 notabug
> thanks
>
>> Date: Thu, 7 Mar 2019 17:27:14 -0800 (PST)
>> From: Drew Adams <drew.adams@oracle.com>
>>
>> See https://emacs.stackexchange.com/a/48221/105.
>>
>> 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.

This is not considered a bug, so I'm closing this bug report.

Best regards,
Stefan Kangas