From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Lars Ingebrigtsen <larsi@gnus.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#14228: 24.3.50;
	doc of `event-start': nonsensical, incomplete, inconsistent
Date: Sat, 08 Feb 2014 17:56:52 -0800
Message-ID: <87r47dkpzv.fsf@building.gnus.org>
References: <2B7219AEF4554855BC07241B6C6A6B6B@us.oracle.com>
	<87zjm1sty1.fsf@building.gnus.org> <83d2ixwu8s.fsf@gnu.org>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain
X-Trace: ger.gmane.org 1391911151 15493 80.91.229.3 (9 Feb 2014 01:59:11 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Sun, 9 Feb 2014 01:59:11 +0000 (UTC)
Cc: 14228@debbugs.gnu.org
To: Eli Zaretskii <eliz@gnu.org>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Feb 09 02:59:18 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 1WCJfw-0000vK-GU
	for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Feb 2014 02:59:16 +0100
Original-Received: from localhost ([::1]:48696 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 1WCJfw-0002gs-68
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 08 Feb 2014 20:59:16 -0500
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45964)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCJfn-0002gf-VP
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 20:59:13 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCJfi-0001Ew-Kv
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 20:59:07 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:44458)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCJfi-0001Er-Hh
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 20:59:02 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1WCJfi-0004kp-7d
	for bug-gnu-emacs@gnu.org; Sat, 08 Feb 2014 20:59:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Lars Ingebrigtsen <larsi@gnus.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sun, 09 Feb 2014 01:59:02 +0000
Resent-Message-ID: <handler.14228.B14228.139191110218208@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.139191110218208
	(code B ref 14228); Sun, 09 Feb 2014 01:59:02 +0000
Original-Received: (at 14228) by debbugs.gnu.org; 9 Feb 2014 01:58:22 +0000
Original-Received: from localhost ([127.0.0.1]:58477 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1WCJf3-0004jb-6L
	for submit@debbugs.gnu.org; Sat, 08 Feb 2014 20:58:21 -0500
Original-Received: from hermes.netfonds.no ([80.91.224.195]:34472)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <larsi@gnus.org>) id 1WCJez-0004jK-Je
	for 14228@debbugs.gnu.org; Sat, 08 Feb 2014 20:58:18 -0500
Original-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 <larsi@gnus.org>)
	id 1WCJek-0003VU-Ur; Sun, 09 Feb 2014 02:58:03 +0100
In-Reply-To: <83d2ixwu8s.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 08 Feb
	2014 16:32:03 +0200")
User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux)
X-MailScanner-ID: 1WCJek-0003VU-Ur
MailScanner-NULL-Check: 1392515883.38946@ajLSor3aifbad5alLhr/cg
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:85008
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/85008>

Eli Zaretskii <eliz@gnu.org> 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/