From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Drew Adams <drew.adams@oracle.com>
Newsgroups: gmane.emacs.bugs
Subject: bug#14228: 24.3.50;
	doc of `event-start': nonsensical, incomplete, inconsistent
Date: Mon, 10 Feb 2014 13:55:13 -0800 (PST)
Message-ID: <a5159a81-3f98-4a10-a8a1-9365f4b2a547@default>
References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com>
	<87zjm1sty1.fsf@building.gnus.org>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
X-Trace: ger.gmane.org 1392069377 21461 80.91.229.3 (10 Feb 2014 21:56:17 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Mon, 10 Feb 2014 21:56:17 +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 Mon Feb 10 22:56:23 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 1WCypz-0005Dp-KX
	for geb-bug-gnu-emacs@m.gmane.org; Mon, 10 Feb 2014 22:56:23 +0100
Original-Received: from localhost ([::1]:58346 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 1WCypz-0004Lw-Ad
	for geb-bug-gnu-emacs@m.gmane.org; Mon, 10 Feb 2014 16:56:23 -0500
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49215)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCypo-0004Lp-46
	for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 16:56:20 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCypf-00061r-F0
	for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 16:56:11 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:34064)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCypf-00061n-Bv
	for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 16:56:03 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCype-0001SW-IH
	for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 16:56:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Drew Adams <drew.adams@oracle.com>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Mon, 10 Feb 2014 21:56:02 +0000
Resent-Message-ID: <handler.14228.B14228.13920693235556@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.13920693235556
	(code B ref 14228); Mon, 10 Feb 2014 21:56:02 +0000
Original-Received: (at 14228) by debbugs.gnu.org; 10 Feb 2014 21:55:23 +0000
Original-Received: from localhost ([127.0.0.1]:41959 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1WCyp1-0001RX-0z
	for submit@debbugs.gnu.org; Mon, 10 Feb 2014 16:55:23 -0500
Original-Received: from aserp1040.oracle.com ([141.146.126.69]:48297)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <drew.adams@oracle.com>) id 1WCyoz-0001RI-3O
	for 14228@debbugs.gnu.org; Mon, 10 Feb 2014 16:55:22 -0500
Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237])
	by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with
	ESMTP id s1ALtEwk024907
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK);
	Mon, 10 Feb 2014 21:55:15 GMT
Original-Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231])
	by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	s1ALtDQ5029699
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
	Mon, 10 Feb 2014 21:55:14 GMT
Original-Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21])
	by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	s1ALtDkd005283; Mon, 10 Feb 2014 21:55:13 GMT
In-Reply-To: <87zjm1sty1.fsf@building.gnus.org>
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8  (707110) [OL
	12.0.6680.5000 (x86)]
X-Source-IP: acsinet21.oracle.com [141.146.126.237]
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:85321
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/85321>

> > 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").
>=20
> 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=20
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.
>=20
> Yeah, they might be nice to understand...
>=20
> > 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').
>=20
> Yup.  Eval the following and enter any keystroke:
>=20
> (event-start (read-event))
> =3D> (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 .
> 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22))
>=20
> Outdated doc string?

Incomplete anyway, and perhaps incorrect.