From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 18 Apr 2013 17:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 14228 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 14228@debbugs.gnu.org X-Debbugs-Original-To: Received: via spool by submit@debbugs.gnu.org id=B.1366305526768 (code B ref -1); Thu, 18 Apr 2013 17:19:01 +0000 Received: (at submit) by debbugs.gnu.org; 18 Apr 2013 17:18:46 +0000 Received: from localhost ([127.0.0.1]:58854 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1USsTt-0000CJ-LF for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:18:46 -0400 Received: from eggs.gnu.org ([208.118.235.92]:57924) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1USsTq-0000C3-Mb for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:18:44 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1USsPU-0000WQ-1g for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:14:13 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-104.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_WHITELIST autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([208.118.235.17]:39443) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1USsPT-0000WM-Uq for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:14:11 -0400 Received: from eggs.gnu.org ([208.118.235.92]:41043) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1USsPS-0001dS-NO for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1USsPQ-0000Vh-Kl for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:10 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:50865) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1USsPQ-0000VY-E6 for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:08 -0400 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r3IHE6LG009065 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 18 Apr 2013 17:14:06 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3IHE5gl011564 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL) for ; Thu, 18 Apr 2013 17:14:06 GMT Received: from abhmt113.oracle.com (abhmt113.oracle.com [141.146.116.65]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3IHE5bU029290 for ; Thu, 18 Apr 2013 17:14:05 GMT Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 18 Apr 2013 10:14:05 -0700 From: "Drew Adams" Date: Thu, 18 Apr 2013 10:14:03 -0700 Message-ID: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac48WB/yPT0V3F4gQiSgVi83fKR3mw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 208.118.235.17 X-Spam-Score: -3.5 (---) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.2 (------) 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"). 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. 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'). But it is more important that nothing is said about what POS is. At least it should be said that it is the value of `point' in the current buffer when the key was pressed, since that seems to always be the case (?). 4. (elisp) `Accessing Mouse' is incomplete. It does not even mention key-press events. Well, of course this is a node about `Accessing Mouse'. But in that case the functions that accept key-press events are documented in the wrong node, since they are not limited to mouse access/events. It is true that `Accessing Mouse' refers to node `Click Events' for the form of the return value. But that description has the same problem wrt key-press events. When, for Emacs 22, you extended these functions to handle key-press events, the doc should have been updated properly. Instead, the Emacs 21 doc was taken as is, with only a "key press" thrown in here and there. Not clear, consistent, and complete. In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600) of 2013-04-15 on ODIEONE Bzr revision: 112292 agustin.martin@hispalinux.es-20130415100014-3vaie95fyec9wk37 Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.7) --no-opt --enable-checking --cflags -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib' From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 08 Feb 2014 11:54:01 +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: To: "Drew Adams" Cc: 14228@debbugs.gnu.org Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.139186041620530 (code B ref 14228); Sat, 08 Feb 2014 11:54:01 +0000 Received: (at 14228) by debbugs.gnu.org; 8 Feb 2014 11:53:36 +0000 Received: from localhost ([127.0.0.1]:56560 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC6TX-0005L4-74 for submit@debbugs.gnu.org; Sat, 08 Feb 2014 06:53:35 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:38557) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC6TS-0005Kt-HV for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 06:53:31 -0500 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 ) id 1WC6TD-0001zJ-Gq; Sat, 08 Feb 2014 12:53:15 +0100 From: Lars Ingebrigtsen References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> Date: Sat, 08 Feb 2014 03:52:06 -0800 In-Reply-To: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> (Drew Adams's message of "Thu, 18 Apr 2013 10:14:03 -0700") Message-ID: <87zjm1sty1.fsf@building.gnus.org> User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1WC6TD-0001zJ-Gq X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392465195.9377@qbAvRUZH8gI7th7pMA5klQ X-Spam-Status: No X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) "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... > 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: (# 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? -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent 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: To: Lars Ingebrigtsen Cc: 14228@debbugs.gnu.org, drew.adams@oracle.com Reply-To: Eli Zaretskii Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.139186993726952 (code B ref 14228); Sat, 08 Feb 2014 14:33:02 +0000 Received: (at 14228) by debbugs.gnu.org; 8 Feb 2014 14:32:17 +0000 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 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 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) 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) Date: Sat, 08 Feb 2014 16:32:03 +0200 From: Eli Zaretskii In-reply-to: <87zjm1sty1.fsf@building.gnus.org> X-012-Sender: halo1@inter.net.il Message-id: <83d2ixwu8s.fsf@gnu.org> References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> <87zjm1sty1.fsf@building.gnus.org> X-Spam-Score: 1.0 (+) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > 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. From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Feb 2014 01:59: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: To: Eli Zaretskii Cc: 14228@debbugs.gnu.org, drew.adams@oracle.com Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.139191110218208 (code B ref 14228); Sun, 09 Feb 2014 01:59:02 +0000 Received: (at 14228) by debbugs.gnu.org; 9 Feb 2014 01:58:22 +0000 Received: from localhost ([127.0.0.1]:58477 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCJf3-0004jb-6L for submit@debbugs.gnu.org; Sat, 08 Feb 2014 20:58:21 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:34472) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCJez-0004jK-Je for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 20:58:18 -0500 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 ) id 1WCJek-0003VU-Ur; Sun, 09 Feb 2014 02:58:03 +0100 From: Lars Ingebrigtsen References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> <87zjm1sty1.fsf@building.gnus.org> <83d2ixwu8s.fsf@gnu.org> Date: Sat, 08 Feb 2014 17:56:52 -0800 In-Reply-To: <83d2ixwu8s.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 08 Feb 2014 16:32:03 +0200") Message-ID: <87r47dkpzv.fsf@building.gnus.org> User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1WCJek-0003VU-Ur X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392515883.38946@ajLSor3aifbad5alLhr/cg X-Spam-Status: No X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) Eli Zaretskii writes: > 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. I'll add some text to that node and an index to point keyboard event positions to it, too. >> > 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). I was thinking more about the more bewildering things at the end there. But I see now that the manual (later in the same section, but I didn't notice) defines a bunch of accessors into the list (like `posn-col-row') and explains what they are. I'll alter the doc string to also mention these accessors, and also give a very brief explanation of how they're used. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 08 21:15:20 2014 Received: (at control) by debbugs.gnu.org; 9 Feb 2014 02:15:20 +0000 Received: from localhost ([127.0.0.1]:58488 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCJvT-0005Dc-KL for submit@debbugs.gnu.org; Sat, 08 Feb 2014 21:15:19 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:37481) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCJvR-0005DU-Rc for control@debbugs.gnu.org; Sat, 08 Feb 2014 21:15:18 -0500 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 ) id 1WCJvC-0003gZ-PX for control@debbugs.gnu.org; Sun, 09 Feb 2014 03:15:03 +0100 Date: Sat, 08 Feb 2014 18:13:52 -0800 Message-Id: <87ppmxkp7j.fsf@building.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #14228 X-MailScanner-ID: 1WCJvC-0003gZ-PX X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392516904.57983@buXfeTo0PFZKpsq1aFM5wg X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) close 14228 24.4 From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Feb 2014 03:47: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: To: Lars Ingebrigtsen Cc: 14228@debbugs.gnu.org, drew.adams@oracle.com Reply-To: Eli Zaretskii Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.139191758124424 (code B ref 14228); Sun, 09 Feb 2014 03:47:02 +0000 Received: (at 14228) by debbugs.gnu.org; 9 Feb 2014 03:46:21 +0000 Received: from localhost ([127.0.0.1]:58709 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCLLV-0006Lp-W7 for submit@debbugs.gnu.org; Sat, 08 Feb 2014 22:46:21 -0500 Received: from mtaout23.012.net.il ([80.179.55.175]:38670) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCLLQ-0006LZ-DP for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 22:46:16 -0500 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0N0P00J00KYPT300@a-mtaout23.012.net.il> for 14228@debbugs.gnu.org; Sun, 09 Feb 2014 05:46:10 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N0P00J7YMGXRA60@a-mtaout23.012.net.il>; Sun, 09 Feb 2014 05:46:10 +0200 (IST) Date: Sun, 09 Feb 2014 05:45:51 +0200 From: Eli Zaretskii In-reply-to: <87r47dkpzv.fsf@building.gnus.org> X-012-Sender: halo1@inter.net.il Message-id: <83vbwpuexc.fsf@gnu.org> References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> <87zjm1sty1.fsf@building.gnus.org> <83d2ixwu8s.fsf@gnu.org> <87r47dkpzv.fsf@building.gnus.org> X-Spam-Score: 1.0 (+) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > From: Lars Ingebrigtsen > Cc: drew.adams@oracle.com, 14228@debbugs.gnu.org > Date: Sat, 08 Feb 2014 17:56:52 -0800 > > >> > 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). > > I was thinking more about the more bewildering things at the end there. They are all described in "Click Events" in the ELisp manual, AFAICS. From unknown Sun Jun 22 08:04:43 2025 X-Loop: help-debbugs@gnu.org Subject: bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent 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: To: Lars Ingebrigtsen Cc: 14228@debbugs.gnu.org Received: via spool by 14228-submit@debbugs.gnu.org id=B14228.13920693235556 (code B ref 14228); Mon, 10 Feb 2014 21:56:02 +0000 Received: (at 14228) by debbugs.gnu.org; 10 Feb 2014 21:55:23 +0000 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 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 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 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 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 MIME-Version: 1.0 Message-ID: Date: Mon, 10 Feb 2014 13:55:13 -0800 (PST) From: Drew Adams References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com> <87zjm1sty1.fsf@building.gnus.org> 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)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Spam-Score: -2.9 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.9 (--) > > 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.