ISSUE-143: DOM3 Events editorial errors

editorial d3e

DOM3 Events editorial errors

State:
CLOSED
Product:
HISTORICAL: DOM3 Events [All Bugs and Issues use Bugzilla: http://tinyurl.com/Bugs-DOM3Events]
Raised by:
Doug Schepers
Opened on:
2010-10-06
Description:
Daniel Barclay <http://lists.w3.org/Archives/Public/www-dom/2010JulSep/0188.html>:
[[
In reading the Document Object Model (DOM) Level 3 Events
Specification, specifically, the version currently (2010-09-23) at
http://www.w3.org/TR/DOM-Level-3-Events/ ("Draft 07 September 2010"),
I noticed a number of mostly editorial errors in Section 2:


* Section 2: The definitions are written in two different styles (some
in complete-sentence style, some in noun-phrase-only style). They
probably should be more consistent. (When you read several in the
complete-sentence style and then start reading one without a main
verb, your parsing of the (partial) sentence gets thrown off.)


* Section 2, dead key: "combination of key" should be "combination of
keys"

* Section 2, dead key: "e.g." should be "e.g.,"

* Various locations: There are other occurrences of "e.g." and of
"i.e." without the standard following comma.

* Section 2, delta: The specification of positive and negative
directions still seems to be ambiguous.

For example, a mouse wheel is in a vertical plane but has a
horizontal axis, so it's not clear whether it would be "vertically-
aligned device" or a "horizontally-aligned device."

(Although much less so, the reference to "the wheel['s being]
rotated towards the user" is also ambiguous. Ideally at least, it
should probably refer to the part of the wheel that the user touches
(since other parts move in other directions).)

* Section 2, event order: unpaired comma

"a mousedown event from the trackpad, followed by a mouseup event
from the mouse would not result in a click event."

should be:

"a mousedown event from the trackpad, followed by a mouseup event
from the mouse, would not result in a click event."

or:

"a mousedown event from the trackpad followed by a mouseup event
from the mouse would not result in a click event. "

* Section 2, event order: "in an environment with a a mouse"

* Section 2, event type: The text says:

The name of an event object which defines particular trigger
conditions and other characteristics which distinguish it from
other event types.

Is "name of an event object" really correct? (It sounds like it's
referring to an object as opposed to a type/kind/class of object,
and like it's specifically referring to the _name_ of that type
as opposed to referring to the type itself (its characteristics).)

* Section 3, focus:

Each element has different behavior when focused, depending on
its functionality, such as priming the element for activation (as
for a button or hyperlink) or toggling state (as for a checkbox),
receiving text input (as for a text form field), or copying
selected text.

Are the commas (and occurrences of "or") correct? As the text is
written, priming and copying are siblings, which doesn't seem right
for typical UI behavior (although it does seem like some X11
selection behavior).

* Section 3, hysteresis: "and no immediately closing a nested menu"
should be "and not ..."

* Section 3, key value: inconsistent singular vs. plural:

Control keys, function keys, modifier keys, dead keys, and others
keys always have a key value, whether or not it has a character
value.

That should probably be:

"A control key, function key, ... always has ...."

(Making is consistently singular will be clearer than the
alternative fix of making everything plural.)

Section 3, phase:

... along the DOM tree, from the defaultView (window), to the
Document object, root element down to the event target (...), at
the event target itself (target phase), and back up to the same
chain ...

Something's not quite right with the wording "to the Document object,
root element down to the event target" section. Maybe that part
should be:

to the Document object, the root element, and down to the event
target

Also, shouldn't the wording "back up to the same chain" be "back up
the same chain"?

Section 3, propagation path:

.. As the event propagates, each event target in the propagation
path shall in turn be set as the Event.currentTarget. ...

Shouldn't that "shall" be "will"? (Isn't it the case that some other
part of the specification specifies that behavior (and needs to use
"shall"), and that the glossary entry should just describe what
happens/will happen with "will"? (The rest of the glossary entries
say what happens, not what "must" happen).

The propagation path is initially comprised of one or more event
phases ...

(Also see the "topmost event target" entry.)


That "is comprised of" should be "comprises" (or "is composed of,"
etc.). (The whole comprises the parts. The whole is not "comprised
of" the parts.) (It appears to be used correctly in the "Unicode
character categories" entry.)

Section 3, text composition system:

A software component which interprets some form of alternate input,
such as a input method editor, a speech processor, or a handwriting
recognition system, and converts it to text.

The "which" should probably be "that." (Also see "which" in the
"topmost event target" entry.)

Something is "distributed" (in the mathematical/arithmetic sense)
wrong. The final "and" phrases seems misplaced; probably, the
"such as" phrase can't go between "interprets" and "converts".

Section 3, Unicode code point:

A Unicode code point is a unique hexadecimal number ...

Is that accurate? In particular, is the code point a number that
_can_ be written in hexadecimal or is the code point really that
hexadecimal representation of the abstract number?

Section 3, user agent:

... retrieving, interpreting, ... content conforming to a
specification.

Should the definition really include "conforming to a
specification"? (If a browser works with content that does not
conform to a specification, is that browser really not a "user
agent," or is it still a user agent, just possibly not a
one that conforms to the DOM Events specification?)
]]

Daniel Barclay <http://lists.w3.org/Archives/Public/www-dom/2010JulSep/0190.html>:
[[
In reading the Document Object Model (DOM) Level 3 Events
Specification, specifically, the version currently (2010-09-23) at
http://www.w3.org/TR/DOM-Level-3-Events/ ("Draft 07 September 2010"),
I noticed a number of mostly editorial errors in Section 3:


Section 3.1:

* The text says:

This ensures that an event object may be properly dispatched
multiple times while also allowing to prevent the event objects
propagation or default actions prior to the event dispatch.

"event objects propagation" should be "event object's propagation"

"allowing to prevent" should be "allowing preventing" (or maybe
"allowing one to prevent")

* The text says:

Such events are handled in a synchronous manner, the event
propagation that causes the event listener to be triggered must
resume only after the event dispatch of the new event is
completed.

The comma should be a semicolon (or a sentence break).


Section 3.2:

* The text says:

An example is the [HTML5] form element.

That should probably be:

An example is the HTML5 [HTML5] form element.

or:

An example is the HTML [HTML5] form element.

or:

An example is the HTML form element [HTML5].

(Note how section 3.3.1 says "HTML5 [HTML5] defines its event
operations...")

* "to associate new default actions to" should probably be "to
associate ... with"


Section 3.3:

* The text says:

Events may occur either synchronously ("sync") or asynchronously
("async").

Events which are synchronous must be ...

Events which are asynchronous may be ...

As written, that defines "sync" as "sychronously" (even though it
really means "synchronous"). (One can have sync events and async
events, but doing something "sync" or doing it "async" either
makes no sense or is very ungrammatical.)

The text should probably say:

Events may occur either synchronously or asynchronously.

Events which are synchronous ("sync events") must be ...

Events which are asynchronous ("sync events") may be ...

* "Each ... are fired ..." should be "Each ... is fired ..."


Section 3.4:

* "Events which are generated ... are trusted" should probably be
"Events that are generated ... are trusted." (Some other uses
of "which" don't seem right either.)

* "events generated by script" should be "... by scripts"

* "have a have a" -> "have a"

* "these activation behavior" -> "these activation behaviors"


Section 3.5:

* "when applying that attributes or attribute value" should
(apparently) be "... those attributes or attribute values"


Section 3.5.1:

* The text says:

"... when it does not result from a user activating a button ..."

Grammatically, that really should be:

"... when it does not result from a user's activating a button ..."

(It's talking about the activating done by the user, not the user
in the state of or in the process of activating.)

* "implementation dependent" -> "implementation-dependent"

* "device dependent" -> "device-dependent", "application dependent"
-> "application-dependent"


** There is a second section 3.5.1.
]]
Related Actions Items:
No related actions
Related emails:
  1. Re: ISSUE-143 (editorial d3e): DOM3 Events section 3 editorial errors [DOM3 Events] (from Jacob.Rossi@microsoft.com on 2011-08-03)
  2. ISSUE-143 (editorial d3e): DOM3 Events section 3 editorial errors [DOM3 Events] (from sysbot+tracker@w3.org on 2010-10-06)

Related notes:

LAST CALL

Doug Schepers, 11 Oct 2010, 17:02:12

Revision 1.179. Fixed errors.

Jacob Rossi, 6 May 2011, 02:10:54

Display change log ATOM feed


Chair, Staff Contact
Tracker: documentation, (configuration for this group), originally developed by Dean Jackson, is developed and maintained by the Systems Team <w3t-sys@w3.org>.
$Id: 143.html,v 1.1 2016/01/25 10:26:15 carine Exp $