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

Previous Next

Full log

View this message in rfc822 format

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

Previous Next

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