Re: ISSUE-143 (editorial d3e): DOM3 Events section 3 editorial errors [DOM3 Events]

Hi Daniel,

Thanks for these great comments. We made your recommended changes to the spec. Let us know if you have additional comments or concerns with this change.

Thanks,

Jacob


===========================================================
From: Web Applications Working Group Issue Tracker <sysbot+tracker@w3.org>
Date: Wed, 06 Oct 2010 06:43:07 +0000
To: public-webapps@w3.org
Message-Id: <E1P3NiV-00015D-KK@otto.w3.org>

ISSUE-143 (editorial d3e): DOM3 Events section 3 editorial errors   [DOM3 Events]

http://www.w3.org/2008/webapps/track/issues/143

Raised by: Doug Schepers
On product: DOM3 Events

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?)
]]

Received on Wednesday, 3 August 2011 17:31:20 UTC