From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii 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 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 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: 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 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 ) 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 ) 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 ) 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 ) 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 ) 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 Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 08 Feb 2014 14:33: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.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 ) 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 ) 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" 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:84964 Archived-At: > From: Lars Ingebrigtsen > Date: Sat, 08 Feb 2014 03:52:06 -0800 > Cc: 14228@debbugs.gnu.org > > "Drew Adams" 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: (# 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)) > => (# 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.