* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
@ 2013-04-18 17:14 Drew Adams
2014-02-08 11:52 ` Lars Ingebrigtsen
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2013-04-18 17:14 UTC (permalink / raw)
To: 14228
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'
^ permalink raw reply [flat|nested] 6+ messages in thread* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
2013-04-18 17:14 bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Drew Adams
@ 2014-02-08 11:52 ` Lars Ingebrigtsen
2014-02-08 14:32 ` Eli Zaretskii
2014-02-10 21:55 ` Drew Adams
0 siblings, 2 replies; 6+ messages in thread
From: Lars Ingebrigtsen @ 2014-02-08 11:52 UTC (permalink / raw)
To: Drew Adams; +Cc: 14228
"Drew Adams" <drew.adams@oracle.com> 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: (#<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').
Yup. Eval the following and enter any keystroke:
(event-start (read-event))
=> (#<window 2044 on *unsent wide reply to Drew Adams*> 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/
^ permalink raw reply [flat|nested] 6+ messages in thread* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
2014-02-08 11:52 ` Lars Ingebrigtsen
@ 2014-02-08 14:32 ` Eli Zaretskii
2014-02-09 1:56 ` Lars Ingebrigtsen
2014-02-10 21:55 ` Drew Adams
1 sibling, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2014-02-08 14:32 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 14228
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 08 Feb 2014 03:52:06 -0800
> Cc: 14228@debbugs.gnu.org
>
> "Drew Adams" <drew.adams@oracle.com> 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: (#<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').
>
> Yup. Eval the following and enter any keystroke:
>
> (event-start (read-event))
> => (#<window 2044 on *unsent wide reply to Drew Adams*> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
2014-02-08 14:32 ` Eli Zaretskii
@ 2014-02-09 1:56 ` Lars Ingebrigtsen
2014-02-09 3:45 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2014-02-09 1:56 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 14228
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
2014-02-09 1:56 ` Lars Ingebrigtsen
@ 2014-02-09 3:45 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2014-02-09 3:45 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 14228
> From: Lars Ingebrigtsen <larsi@gnus.org>
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent
2014-02-08 11:52 ` Lars Ingebrigtsen
2014-02-08 14:32 ` Eli Zaretskii
@ 2014-02-10 21:55 ` Drew Adams
1 sibling, 0 replies; 6+ messages in thread
From: Drew Adams @ 2014-02-10 21:55 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 14228
> > 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...
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
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.
>
> 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: (#<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').
>
> Yup. Eval the following and enter any keystroke:
>
> (event-start (read-event))
> => (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 .
> 462) 0 nil 1660 (0 . 21) nil (0 . 0) (11 . 22))
>
> Outdated doc string?
Incomplete anyway, and perhaps incorrect.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-02-10 21:55 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-04-18 17:14 bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent Drew Adams
2014-02-08 11:52 ` Lars Ingebrigtsen
2014-02-08 14:32 ` Eli Zaretskii
2014-02-09 1:56 ` Lars Ingebrigtsen
2014-02-09 3:45 ` Eli Zaretskii
2014-02-10 21:55 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).