GNU bug report logs - #26626
24.5; doc of `last-command-event' and `last-nonmenu-event'

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 26626 in the body.
You can then email your comments to 26626 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: 24.5; doc of `last-command-event' and `last-nonmenu-event'
Date: Sun, 23 Apr 2017 10:35:19 -0700 (PDT)

The doc is not very clear - both (elisp) `Command Loop Info' and the doc
strings.

The essential difference in the descriptions seems to be the last input
event read "as part of a key sequence" versus read "as part of a
command".  But "read as part of a command" is unclear.  Does it mean
read by a command (e.g., by a call to `read-char' within the command
definition)?  No.  But that's all I can think of, when reading that
description.

The doc of `last-nonmenu-event' is pretty clear.  Or at least it is
before reading also the doc of `last-command-event' and trying to make
sense of that.  Even the name of the latter is unclear - what's a
"command event"?

The example given for `last-command-event' suggests that what is meant
is the last event in the key sequence that invoked/initiated a command.
I think that's closer to what the meaning/behavior is.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26626 <at> debbugs.gnu.org
Subject: Re: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Fri, 26 Jul 2019 11:33:07 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> The doc is not very clear - both (elisp) `Command Loop Info' and the doc
> strings.

I think the manual is pretty clear:

---

@defvar last-command-event
This variable is set to the last input event that was read by the
command loop as part of a command.  The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
character to insert.

@example
@group
last-command-event
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} 5
@end group
@end example

@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
@end defvar

---

The example helps a lot.  

> The essential difference in the descriptions seems to be the last input
> event read "as part of a key sequence" versus read "as part of a
> command".  But "read as part of a command" is unclear.  Does it mean
> read by a command (e.g., by a call to `read-char' within the command
> definition)?  No.  But that's all I can think of, when reading that
> description.
>
> The doc of `last-nonmenu-event' is pretty clear.  Or at least it is
> before reading also the doc of `last-command-event' and trying to make
> sense of that.  Even the name of the latter is unclear - what's a
> "command event"?
>
> The example given for `last-command-event' suggests that what is meant
> is the last event in the key sequence that invoked/initiated a command.
> I think that's closer to what the meaning/behavior is.

The variable doc string isn't very helpful; no.

I've now changed it to the following on the trunk:

Last input event that was part of a command key sequence.
See Info node `(elisp)Command Loop Info'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26626 <at> debbugs.gnu.org
Subject: RE: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Fri, 26 Jul 2019 07:30:20 -0700 (PDT)

> > The essential difference in the descriptions seems to be the last input
> > event read "as part of a key sequence" versus read "as part of a
> > command".  But "read as part of a command" is unclear.  Does it mean
> > read by a command (e.g., by a call to `read-char' within the command
> > definition)?  No.  But that's all I can think of, when reading that
> > description.
> >
> > The doc of `last-nonmenu-event' is pretty clear.  Or at least it is
> > before reading also the doc of `last-command-event' and trying to make
> > sense of that.  Even the name of the latter is unclear - what's a
> > "command event"?
> >
> > The example given for `last-command-event' suggests that what is
> > meant is the last event in the key sequence that invoked/initiated a
> > command.  I think that's closer to what the meaning/behavior is.
> 
> The variable doc string isn't very helpful; no.
> 
> I've now changed it to the following on the trunk:
> 
> Last input event that was part of a command key sequence.
> See Info node `(elisp)Command Loop Info'.

There's no such thing as a "command key sequence",
as opposed, one imagines, to a "non-command key
sequence".  A key sequence that is complete is
always bound to a command.

Or did you mean to suggest a complete key sequence,
as opposed to an incomplete sequence: a key-sequence
prefix?

There are events that are not key sequences.  That
distinction is valid and important.  But are there
(complete) key sequences that are not bound to keys
(including menu and mouse actions)?  I don't think
so.

I still think that the text for this should borrow
from what is said for `last-nonmenu-event'.  IIUC,
`last-command-event' is the "last input event read
as part of a key sequence".

IOW, same as `last-nonmenu-event', but without the
"nonmenu" part.  Isn't that the essential difference?

And yes, the Info description should be changed,
not just the doc string, for the reasons given in
the bug description - "as part of a command" is
misleading or meaningless.  See above for a
suggestion: make it similar to what we say for
`last-nonmenu-event'.

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#26626: 24.5;
 doc of `last-command-event' and `last-nonmenu-event'
Date: Fri, 26 Jul 2019 16:49:14 +0200

On Jul 26 2019, Drew Adams <drew.adams <at> oracle.com> wrote:

> There's no such thing as a "command key sequence",
> as opposed, one imagines, to a "non-command key
> sequence".  A key sequence that is complete is
> always bound to a command.

Not true.  Everything that isn't a prefix key is a complete key, bound
or not.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#26626: 24.5;
 doc of `last-command-event' and `last-nonmenu-event'
Date: Fri, 26 Jul 2019 10:50:21 -0400

Drew Adams <drew.adams <at> oracle.com> writes:

> There's no such thing as a "command key sequence",
> as opposed, one imagines, to a "non-command key
> sequence".

It's just what you said in the OP: "the key sequence that
invoked/initiated a command".

> I still think that the text for this should borrow
> from what is said for `last-nonmenu-event'.  IIUC,
> `last-command-event' is the "last input event read
> as part of a key sequence".

That would be misleading.

(list :last-command-event last-command-event
      :last-input-event last-input-event
      :last-nonmenu-event last-nonmenu-event
      (read-key-sequence "Key seq: ")
      :last-command-event last-command-event
      :last-input-event last-input-event
      :last-nonmenu-event last-nonmenu-event)
; C-x C-e =>
(:last-command-event 5 :last-input-event 5 :last-nonmenu-event 5
 "\^C\^C"
 :last-command-event 5 :last-input-event 3 :last-nonmenu-event 3)

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Fri, 26 Jul 2019 08:37:14 -0700 (PDT)

> > There's no such thing as a "command key sequence",
> > as opposed, one imagines, to a "non-command key
> > sequence".  A key sequence that is complete is
> > always bound to a command.
> 
> Not true.  Everything that isn't a prefix key is a complete key, bound
> or not.

Right.  I misspoke.  I didn't mean that only bound
key sequences are complete key sequences.

The point is that there's no such thing as a "command"
key sequence", just as there's no such thing as a
non-command key sequence.  Key sequences can be bound
only to commands - not to anything else.  Commands
can be bound to key sequences - not to anything else.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Fri, 26 Jul 2019 08:46:21 -0700 (PDT)

> > There's no such thing as a "command key sequence",
> > as opposed, one imagines, to a "non-command key
> > sequence".
> 
> It's just what you said in the OP: "the key sequence that
> invoked/initiated a command".

Yes, that's still the best way to put it, I think.

> > I still think that the text for this should borrow
> > from what is said for `last-nonmenu-event'.  IIUC,
> > `last-command-event' is the "last input event read
> > as part of a key sequence".
> 
> That would be misleading.

You're right.  It's the first input event read
as part of a key sequence - not the last such.

The larger point was that it is an input event
read as part of a key sequence.  But yes, you're
absolutely right that the text for
`last-nonmenu-event' needs more of a tweak than
the one I gave it.

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#26626: 24.5;
 doc of `last-command-event' and `last-nonmenu-event'
Date: Fri, 26 Jul 2019 11:50:42 -0400

Drew Adams <drew.adams <at> oracle.com> writes:

>> > `last-command-event' is the "last input event read
>> > as part of a key sequence".
>> 
>> That would be misleading.
>
> You're right.  It's the first input event read
> as part of a key sequence - not the last such.

No, it's the last event read as part "the key sequence that
invoked/initiated a command".  But I see that my example was bad,
because I gave a key sequence (C-c C-c) which has the same event in both
first and last place.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Fri, 26 Jul 2019 08:53:18 -0700 (PDT)

> No, it's the last event read as part "the key sequence that
> invoked/initiated a command".  But I see that my example was bad,
> because I gave a key sequence (C-c C-c) which has the same event in
> both first and last place.

OK.

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#26626: 24.5;
 doc of `last-command-event' and `last-nonmenu-event'
Date: Fri, 26 Jul 2019 17:43:20 -0400

Drew Adams <drew.adams <at> oracle.com> writes:

>> > There's no such thing as a "command key sequence",
>> > as opposed, one imagines, to a "non-command key
>> > sequence".
>> 
>> It's just what you said in the OP: "the key sequence that
>> invoked/initiated a command".
>
> Yes, that's still the best way to put it, I think.

I reworded the docstring to say that.

d04b0ae7b1 2019-07-26T17:25:08-04:00 "Clarify docstring of last-command-event."
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=d04b0ae7b1c8edbf452bd40f5e50f8e750a66e06

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 26626 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: bug#26626: 24.5; doc of `last-command-event' and
 `last-nonmenu-event'
Date: Sat, 27 Jul 2019 00:25:29 +0000 (UTC)

> >> It's just what you said in the OP: "the key sequence that
> >> invoked/initiated a command".
> >
> > Yes, that's still the best way to put it, I think.
> 
> I reworded the docstring to say that.

Thanks to all for working on this.

Previous Next

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