GNU bug report logs - #14228
24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent

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 14228 in the body.
You can then email your comments to 14228 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.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
Date: Thu, 18 Apr 2013 10:14:03 -0700

This pertains to `event-start' and `event-end' (and perhaps to more).
 
1. The doc string and (elisp) `Accessing Mouse' do not agree.  The
former says that arg EVENT can be a "key press event".  The latter
limits it to mouse events ("the data in a mouse button or motion
event").
 
2. The doc string of `event-start' specifies the form of EVENT as being
either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
 
But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
etc.  Incomprehensible.
 
3. In particular, the doc string says that if EVENT is a key press event
then the value returned by `event-start' has the form (WINDOW POS (0.0)
0).  What is POS?
 
Anyway, looking at the code and experimenting, it does NOT seem that
`event-start' always returns the form (WINDOW POS (0.0) 0).  I sometimes
see a form like this, for instance: (#<window 03FC1840 on foobar> 132
(231 . 24) 0 nil 132 (33 . 2) nil (0 . 0) (7 . 12)) (which is what is
returned by `posn-at-point').
 
But it is more important that nothing is said about what POS is.  At
least it should be said that it is the value of `point' in the current
buffer when the key was pressed, since that seems to always be the case
(?).
 
4. (elisp) `Accessing Mouse' is incomplete.  It does not even mention
key-press events.  Well, of course this is a node about `Accessing
Mouse'.  But in that case the functions that accept key-press events are
documented in the wrong node, since they are not limited to mouse
access/events.
 
It is true that `Accessing Mouse' refers to node `Click Events' for the
form of the return value.  But that description has the same problem wrt
key-press events.
 
When, for Emacs 22, you extended these functions to handle key-press
events, the doc should have been updated properly.  Instead, the Emacs
21 doc was taken as is, with only a "key press" thrown in here and
there.
 
Not clear, consistent, and complete.


In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-15 on ODIEONE
Bzr revision: 112292
agustin.martin <at> hispalinux.es-20130415100014-3vaie95fyec9wk37
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 14228 <at> debbugs.gnu.org
Subject: Re: bug#14228: 24.3.50;
 doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 03:52:06 -0800

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

> This pertains to `event-start' and `event-end' (and perhaps to more).
>
> 1. The doc string and (elisp) `Accessing Mouse' do not agree.  The
> former says that arg EVENT can be a "key press event".  The latter
> limits it to mouse events ("the data in a mouse button or motion
> event").

Well, it's in the mouse event section, so it might make sense to just
document the mouse-relevant stuff...

> 2. The doc string of `event-start' specifies the form of EVENT as being
> either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
> OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
>
> But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
> etc.  Incomprehensible.

Yeah, they might be nice to understand...

> 3. In particular, the doc string says that if EVENT is a key press event
> then the value returned by `event-start' has the form (WINDOW POS (0.0)
> 0).  What is POS?
>
> Anyway, looking at the code and experimenting, it does NOT seem that
> `event-start' always returns the form (WINDOW POS (0.0) 0).  I sometimes
> see a form like this, for instance: (#<window 03FC1840 on foobar> 132
> (231 . 24) 0 nil 132 (33 . 2) nil (0 . 0) (7 . 12)) (which is what is
> returned by `posn-at-point').

Yup.  Eval the following and enter any keystroke:

(event-start (read-event))
=> (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 . 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22))

Outdated doc string?

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 14228 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#14228: 24.3.50;
 doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 16:32:03 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Sat, 08 Feb 2014 03:52:06 -0800
> Cc: 14228 <at> debbugs.gnu.org
> 
> "Drew Adams" <drew.adams <at> oracle.com> writes:
> 
> > This pertains to `event-start' and `event-end' (and perhaps to more).
> >
> > 1. The doc string and (elisp) `Accessing Mouse' do not agree.  The
> > former says that arg EVENT can be a "key press event".  The latter
> > limits it to mouse events ("the data in a mouse button or motion
> > event").
> 
> Well, it's in the mouse event section, so it might make sense to just
> document the mouse-relevant stuff...

It should probably also say that other event types are supported.
Unless that is described somewhere else in the manual (in which case
there should be a cross-reference there), but it doesn't seem to be
described in any other place.

> > 2. The doc string of `event-start' specifies the form of EVENT as being
> > either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
> > OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
> >
> > But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
> > etc.  Incomprehensible.
> 
> Yeah, they might be nice to understand...

The doc string of event-start says "AREA-OR-POS".  And if that is
still unclear, there's a reference to "Click Events" in the manual,
which spells that out (except that it uses POS-OR-AREA" instead).

> > 3. In particular, the doc string says that if EVENT is a key press event
> > then the value returned by `event-start' has the form (WINDOW POS (0.0)
> > 0).  What is POS?
> >
> > Anyway, looking at the code and experimenting, it does NOT seem that
> > `event-start' always returns the form (WINDOW POS (0.0) 0).  I sometimes
> > see a form like this, for instance: (#<window 03FC1840 on foobar> 132
> > (231 . 24) 0 nil 132 (33 . 2) nil (0 . 0) (7 . 12)) (which is what is
> > returned by `posn-at-point').
> 
> Yup.  Eval the following and enter any keystroke:
> 
> (event-start (read-event))
> => (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 . 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22))
> 
> Outdated doc string?

Yes, definitely.  But the ELisp manual is up to date, AFAICS.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 14228 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#14228: 24.3.50;
 doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 17:56:52 -0800

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

> It should probably also say that other event types are supported.
> Unless that is described somewhere else in the manual (in which case
> there should be a cross-reference there), but it doesn't seem to be
> described in any other place.

I'll add some text to that node and an index to point keyboard event
positions to it, too.

>> > 2. The doc string of `event-start' specifies the form of EVENT as being
>> > either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
>> > OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
>> >
>> > But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
>> > etc.  Incomprehensible.
>> 
>> Yeah, they might be nice to understand...
>
> The doc string of event-start says "AREA-OR-POS".  And if that is
> still unclear, there's a reference to "Click Events" in the manual,
> which spells that out (except that it uses POS-OR-AREA" instead).

I was thinking more about the more bewildering things at the end there.
But I see now that the manual (later in the same section, but I didn't
notice) defines a bunch of accessors into the list (like `posn-col-row')
and explains what they are.

I'll alter the doc string to also mention these accessors, and also give
a very brief explanation of how they're used.

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 14228 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#14228: 24.3.50;
 doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sun, 09 Feb 2014 05:45:51 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: drew.adams <at> oracle.com,  14228 <at> debbugs.gnu.org
> Date: Sat, 08 Feb 2014 17:56:52 -0800
> 
> >> > 2. The doc string of `event-start' specifies the form of EVENT as being
> >> > either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
> >> > OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
> >> >
> >> > But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
> >> > etc.  Incomprehensible.
> >> 
> >> Yeah, they might be nice to understand...
> >
> > The doc string of event-start says "AREA-OR-POS".  And if that is
> > still unclear, there's a reference to "Click Events" in the manual,
> > which spells that out (except that it uses POS-OR-AREA" instead).
> 
> I was thinking more about the more bewildering things at the end there.

They are all described in "Click Events" in the ELisp manual, AFAICS.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 14228 <at> debbugs.gnu.org
Subject: RE: bug#14228: 24.3.50; doc of `event-start': nonsensical,
 incomplete, inconsistent
Date: Mon, 10 Feb 2014 13:55:13 -0800 (PST)

> > 1. The doc string and (elisp) `Accessing Mouse' do not agree.  The
> > former says that arg EVENT can be a "key press event".  The latter
> > limits it to mouse events ("the data in a mouse button or motion
> > event").
> 
> Well, it's in the mouse event section, so it might make sense to
> just document the mouse-relevant stuff...

On its own, that is a reasonable argument.  The problem with that is
that these functions are, for some reason, documented ONLY in this
node, i.e., in the context of mouse events.  But they are general 
functions, not limited to mouse events.

Ideally their doc should be moved elsewhere (and a cross-ref added
to this node, to point there).  But whether it is thus moved or not,
the functions need to be documented properly.  Their generality does
not change, nor should their descriptions change, just because they
are documented in a mouse-specific node.

IOW, the first fix is to make the descriptions general.  If we can
then also move those corrected descriptions elsewhere, so much the
better.

> > 2. The doc string of `event-start' specifies the form of EVENT as
> > being either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y)
> > TIMESTAMP OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
> >
> > But *none* of those terms are described.  What is POS? IMAGE?
> > OBJECT? etc.  Incomprehensible.
> 
> Yeah, they might be nice to understand...
> 
> > 3. In particular, the doc string says that if EVENT is a key press
> > event then the value returned by `event-start' has the form (WINDOW
> > POS (0.0) 0).  What is POS?
> >
> > Anyway, looking at the code and experimenting, it does NOT seem
> > that `event-start' always returns the form (WINDOW POS (0.0) 0).
> > I sometimes see a form like this, for instance: (#<window 03FC1840
> > on foobar> 132 (231 . 24) 0 nil 132 (33 . 2) nil (0 . 0) (7 . 12))
> > (which is what is returned by `posn-at-point').
> 
> Yup.  Eval the following and enter any keystroke:
> 
> (event-start (read-event))
> => (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 .
> 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22))
> 
> Outdated doc string?

Incomplete anyway, and perhaps incorrect.

Previous Next

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