From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams 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: 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 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: 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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 Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 10 Feb 2014 21:56:02 +0000 Resent-Message-ID: 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 ) 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 ) 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" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: > > 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: (# > 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> (# 1660 (0 . > 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22)) >=20 > Outdated doc string? Incomplete anyway, and perhaps incorrect.