GNU bug report logs - #34784
26.1; Doc of pseudofunction key `<timeout>'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 34784 in the body.
You can then email your comments to 34784 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; Doc of pseudofunction key `<timeout>'
Date: Thu, 7 Mar 2019 17:27:14 -0800 (PST)

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

Message #8 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: 34784 <at> debbugs.gnu.org
Subject: RE: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Thu, 7 Mar 2019 17:29:44 -0800 (PST)

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

Message #11 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: Re: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 08 Mar 2019 15:33:47 +0200

tags 34784 notabug
thanks

> Date: Thu, 7 Mar 2019 17:27:14 -0800 (PST)
> From: Drew Adams <drew.adams <at> 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.

Message #16 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 34784 <at> debbugs.gnu.org
Subject: RE: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 8 Mar 2019 08:52:46 -0800 (PST)

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

Message #19 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: Re: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 08 Mar 2019 19:02:31 +0200

> Date: Fri, 8 Mar 2019 08:52:46 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 34784 <at> 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.

Message #22 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: RE: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 8 Mar 2019 09:20:19 -0800 (PST)

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

Message #25 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: Re: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 08 Mar 2019 20:51:41 +0200

> Date: Fri, 8 Mar 2019 09:20:19 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 34784 <at> 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.

Message #28 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: RE: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 8 Mar 2019 11:39:29 -0800 (PST)

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

Message #31 received at 34784 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 34784 <at> debbugs.gnu.org
Subject: Re: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Fri, 08 Mar 2019 21:48:39 +0200

> Date: Fri, 8 Mar 2019 11:39:29 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 34784 <at> 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.

Message #36 received at 34784-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 34784-done <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#34784: 26.1; Doc of pseudofunction key `<timeout>'
Date: Mon, 24 Aug 2020 12:22:13 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

> tags 34784 notabug
> thanks
>
>> Date: Thu, 7 Mar 2019 17:27:14 -0800 (PST)
>> From: Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.