bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent

[Lars Ingebrigtsen <larsi@gnus.org>]

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/