bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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'

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Andreas Schwab]

On Jul 26 2019, Drew Adams <drew.adams@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@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Noam Postavsky]

Drew Adams <drew.adams@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)

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Noam Postavsky]

Drew Adams <drew.adams@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.

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Noam Postavsky]

Drew Adams <drew.adams@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

bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

[Drew Adams]

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