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: Thu, 18 Apr 2013 10:14:03 -0700
Message-ID: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Trace: ger.gmane.org 1366305280 11542 80.91.229.3 (18 Apr 2013 17:14:40 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Thu, 18 Apr 2013 17:14:40 +0000 (UTC)
To: 14228@debbugs.gnu.org
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Apr 18 19:14:44 2013
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 1USsPy-0002IA-Pj
	for geb-bug-gnu-emacs@m.gmane.org; Thu, 18 Apr 2013 19:14:43 +0200
Original-Received: from localhost ([::1]:58196 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 1USsPy-0001jh-CC
	for geb-bug-gnu-emacs@m.gmane.org; Thu, 18 Apr 2013 13:14:42 -0400
Original-Received: from eggs.gnu.org ([208.118.235.92]:41136)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1USsPu-0001ih-7a
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:39 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1USsPo-0000ZL-Qa
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:38 -0400
Original-Received: from debbugs.gnu.org ([140.186.70.43]:54745)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1USsPo-0000ZH-ND
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:32 -0400
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1USsUA-0000Cz-0l
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:19:02 -0400
X-Loop: help-debbugs@gnu.org
Resent-From: "Drew Adams" <drew.adams@oracle.com>
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: <handler.14228.B.1366305526768@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: report 14228
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: 
X-Debbugs-Original-To: <bug-gnu-emacs@gnu.org>
Original-Received: via spool by submit@debbugs.gnu.org id=B.1366305526768
	(code B ref -1); Thu, 18 Apr 2013 17:19:01 +0000
Original-Received: (at submit) by debbugs.gnu.org; 18 Apr 2013 17:18:46 +0000
Original-Received: from localhost ([127.0.0.1]:58854 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1USsTt-0000CJ-LF
	for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:18:46 -0400
Original-Received: from eggs.gnu.org ([208.118.235.92]:57924)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@oracle.com>) id 1USsTq-0000C3-Mb
	for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:18:44 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@oracle.com>) id 1USsPU-0000WQ-1g
	for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:14:13 -0400
Original-Received: from lists.gnu.org ([208.118.235.17]:39443)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@oracle.com>) id 1USsPT-0000WM-Uq
	for submit@debbugs.gnu.org; Thu, 18 Apr 2013 13:14:11 -0400
Original-Received: from eggs.gnu.org ([208.118.235.92]:41043)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@oracle.com>) id 1USsPS-0001dS-NO
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:11 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@oracle.com>) id 1USsPQ-0000Vh-Kl
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:10 -0400
Original-Received: from userp1040.oracle.com ([156.151.31.81]:50865)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@oracle.com>) id 1USsPQ-0000VY-E6
	for bug-gnu-emacs@gnu.org; Thu, 18 Apr 2013 13:14:08 -0400
Original-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 <bug-gnu-emacs@gnu.org>; Thu, 18 Apr 2013 17:14:06 GMT
Original-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 <bug-gnu-emacs@gnu.org>; Thu, 18 Apr 2013 17:14:06 GMT
Original-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 <bug-gnu-emacs@gnu.org>; Thu, 18 Apr 2013 17:14:05 GMT
Original-Received: from dradamslap1 (/130.35.178.8)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Thu, 18 Apr 2013 10:14:05 -0700
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-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.13
Precedence: list
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.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:73493
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/73493>

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: (#<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').
 
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'