From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Eli Zaretskii <eliz@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#14228: 24.3.50;
	doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 16:32:03 +0200
Message-ID: <83d2ixwu8s.fsf@gnu.org>
References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com>
	<87zjm1sty1.fsf@building.gnus.org>
Reply-To: Eli Zaretskii <eliz@gnu.org>
NNTP-Posting-Host: plane.gmane.org
X-Trace: ger.gmane.org 1391869992 12686 80.91.229.3 (8 Feb 2014 14:33:12 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Sat, 8 Feb 2014 14:33:12 +0000 (UTC)
Cc: 14228@debbugs.gnu.org
To: Lars Ingebrigtsen <larsi@gnus.org>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 08 15:33:18 2014
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane.org
Original-Received: from lists.gnu.org ([208.118.235.17])
	by plane.gmane.org with esmtp (Exim 4.69)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1WC8y5-0000bY-3X
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 15:33:17 +0100
Original-Received: from localhost ([::1]:46838 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1WC8y4-0008Gr-OT
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 09:33:16 -0500
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35020)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC8xw-0008GX-QJ
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 09:33:13 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC8xr-0003qx-SW
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 09:33:08 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:42763)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC8xr-0003qs-Of
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 09:33:03 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC8xq-00072E-L9
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 09:33:03 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Eli Zaretskii <eliz@gnu.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sat, 08 Feb 2014 14:33:02 +0000
Resent-Message-ID: <handler.14228.B14228.139186993726952@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 14228
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: 
Original-Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.139186993726952
	(code B ref 14228); Sat, 08 Feb 2014 14:33:02 +0000
Original-Received: (at 14228) by debbugs.gnu.org; 8 Feb 2014 14:32:17 +0000
Original-Received: from localhost ([127.0.0.1]:56769 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1WC8x3-00070Z-NK
	for submit@debbugs.gnu.org; Sat, 08 Feb 2014 09:32:17 -0500
Original-Received: from mtaout23.012.net.il ([80.179.55.175]:54119)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <eliz@gnu.org>) id 1WC8wx-00070N-ED
	for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 09:32:11 -0500
Original-Received: from conversion-daemon.a-mtaout23.012.net.il by
	a-mtaout23.012.net.il (HyperSendmail v2007.08) id
	<0N0O00H00L8YP400@a-mtaout23.012.net.il> for 14228@debbugs.gnu.org;
	Sat, 08 Feb 2014 16:32:05 +0200 (IST)
Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il
	(HyperSendmail v2007.08) with ESMTPA id
	<0N0O00H6PLPHJR90@a-mtaout23.012.net.il>;
	Sat, 08 Feb 2014 16:32:05 +0200 (IST)
In-reply-to: <87zjm1sty1.fsf@building.gnus.org>
X-012-Sender: halo1@inter.net.il
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x
X-Received-From: 140.186.70.43
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
	the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Xref: news.gmane.org gmane.emacs.bugs:84964
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/84964>

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 08 Feb 2014 03:52:06 -0800
> Cc: 14228@debbugs.gnu.org
> 
> "Drew Adams" <drew.adams@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.