From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Lars Ingebrigtsen <larsi@gnus.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#14228: 24.3.50;
	doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 03:52:06 -0800
Message-ID: <87zjm1sty1.fsf@building.gnus.org>
References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain
X-Trace: ger.gmane.org 1391860448 13675 80.91.229.3 (8 Feb 2014 11:54:08 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Sat, 8 Feb 2014 11:54:08 +0000 (UTC)
Cc: 14228@debbugs.gnu.org
To: "Drew Adams" <drew.adams@oracle.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 08 12:54:16 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 1WC6UB-00070x-MH
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 12:54:15 +0100
Original-Received: from localhost ([::1]:46211 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 1WC6UA-0007WL-S3
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 06:54:14 -0500
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38582)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC6U3-0007W3-K8
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 06:54:12 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC6Ty-0000hX-L4
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 06:54:07 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:42541)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC6Ty-0000hT-Hx
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 06:54:02 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WC6Ty-0005Lx-5R
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 06:54:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Lars Ingebrigtsen <larsi@gnus.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sat, 08 Feb 2014 11:54:01 +0000
Resent-Message-ID: <handler.14228.B14228.139186041620530@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.139186041620530
	(code B ref 14228); Sat, 08 Feb 2014 11:54:01 +0000
Original-Received: (at 14228) by debbugs.gnu.org; 8 Feb 2014 11:53:36 +0000
Original-Received: from localhost ([127.0.0.1]:56560 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1WC6TX-0005L4-74
	for submit@debbugs.gnu.org; Sat, 08 Feb 2014 06:53:35 -0500
Original-Received: from hermes.netfonds.no ([80.91.224.195]:38557)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <larsi@gnus.org>) id 1WC6TS-0005Kt-HV
	for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 06:53:31 -0500
Original-Received: from [204.14.154.233] (helo=building.gnus.org)
	by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16)
	(Exim 4.72) (envelope-from <larsi@gnus.org>)
	id 1WC6TD-0001zJ-Gq; Sat, 08 Feb 2014 12:53:15 +0100
In-Reply-To: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> (Drew Adams's
	message of "Thu, 18 Apr 2013 10:14:03 -0700")
User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux)
X-MailScanner-ID: 1WC6TD-0001zJ-Gq
MailScanner-NULL-Check: 1392465195.9377@qbAvRUZH8gI7th7pMA5klQ
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:84942
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/84942>

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

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