DOM Level 3 Events - minor comments

This is a list of typos and other minor formatting problems that I
encountered while going through the current DOM Level 3 Event spec. A few
of the things listed here are actual errors, but the majority fall into two
categories:
* Initial capital letter missing at the start of a note or warning.
* Sentences glued together with a semi-colon instead of using periods and
starting a new sentence. I didn't call out all of these.

Many of these are perhaps a bit nit-picky, so please consider them
suggestions or feel free to ignore if you disagree.

-Gary


1.3 Stylistic Conventions
=========================

I'm not sure if it's worth listing them here or not, but the following
stylistic conventions are not mentioned in this section even through they
are used in the document:
* Light green for constants (not to be confused with the brighter green
highlighting used for character values.
* Yellow for attributes
* Blue for methods
* Pink for parameters
* Orange (with red text) for event types. Actually, these are somewhat hard
to read. Has this particular text formatting been verified to be readable
by people with color vision problems?

2. Glossary
===========

In *character value*, "Note: in source code..." should begin with a capital

In *candidate event handlers*, "...released or un-frozen after this set of
of candidate event handlers..." has duplicate 'of'

In *event listener*, "Note: ...will be provided as the first paramter to
the user-defined function..." -> spelling of parameter

In *event order*, "Note: there can be..." needs initial cap

In *focus ring*, "A focus ring is a an ordered set of..." remove 'a'

In *Unicode character categories", The term "General Category" is
capitalized in official Unicode documentation. Suggest rewrite as "A subset
of the General Category values that are defined for each Unicode code
point. This subset contains all the Letter (Ll, Lm, Lo, Lt, Lu), Number
(Nd, Nl, No), Punctuation (Pc, Pd, Pe, Pf, Pi, Po, Ps) and Symbol (Sc, Sk,
Sm, So) category values."

3.1 Event dispatch and DOM event flow
=====================================

Caption for Figure 1 should be centered and start with a capital letter.

"... The exception itself must not propogate outside the scope of the event
handler." Spelling of 'propagate'

In Example: "In the following code, the exception thrown from the call to
throw "Error" does not propogate into the parent scope, (which would
prevent the console.log statement from executing):" Comma before paren
looks awkward. Spelling of 'propagate'.

"This specification defines three event phases: capture phase; target
phase; and bubble phase." semi-colons should be commas

"The capture phase: the event object must propagate..." initial cap since
it starts a sentence. Same for 1, 2 and 3 in this list.

3.2 Default actions and cancelable events
=========================================

In first Example, "...depends on what happens next--for example, if the
user's pointing..." double hyphen should be proper em-dash.

In second Example, "...event on <input type="checkbox"> elements..." the
<input> tag and attributes should be in a monospace font

3.3 Synchronous and asynchronous events
=======================================

"...ordered by sequence of temporal occurrence, with respect to other
events, to changes in the DOM..." comma after occurrence makes this harder
to read.

In first Example, 'keydown' event is listed, but there is no corresponding
'keyup'. Is this intentional?

3.5.1 Activation event synthesis
================================

"...of the default actions of that activation trigger; the value of the
Event.target..." Period instead of semi-colon to ease readability.

3.6 Event exceptions
====================

"Note: the exception EventException..." initial cap.

4. Basic Event Interfaces
=========================

"Figure 2: graphical representation of the DOM3 Events interface
inheritance" should have initial capital for 'Graphical'

4.1 Interface Event
===================

For eventPhase, "The un-initialized value of this attribute must be 0."
could mention the defined constant NONE. Suggest: "The un-initialized value
of this attribute must be 0 (NONE)."

For stopImmediatePropagation, I think it would look better if the
"introduced in DOM Level 3" was enclosed in parentheses, as is done above
for "Interface Event (introduced in DOM Level 2)". But that change would
need to be made throughout this document for consistency.

4.3 Interface EventTarget
=========================

In the first Note, "...event type (see the List of DOM3 Event Types); for
example, a mouseover event type..." Semi-colon -> period. The sentence is
long enough already.

The second Note uses italics for the code in "...use of attributes, e.g.,
onclick="handleClick()" (see [HTML5]...". This isn't consistent with code
elsewhere, so I don't believe it was intentional.

addEventListener and removeEventListener should have a "modified in DOM
Level 3" note just like dispatchEvent.

dispatchEvent might benefit from an "Authoring Note" (like addEventListener
and removeEventListener) that describes the modifications from DOM Level 2.

In dispatchEvent, "Note: while a dispatch..." initial capital.

4.5 Interface DocumentEvent
===========================

createEvent has a "Modified in DOM Level 3" comment in the WebIDL
Definition, but is missing a note next to its name. An "Authoring Note"
might also be useful here.

5.1.1 List of DOM3 Event Types
==============================

'keypress' is marked as deprecated elsewhere in this doc so it might
benefit from a "Warning! Deprecated" note here as well.

5.2.1 User Interface Event Types
================================

'load': In "Note: for legacy reasons..." initial cap

5.2.2.1 Focus Event Order
=========================

In Note: "...such as focus() or blur(); see the relevant specifications..."
Semi-colon -> period.

5.2.2.2 Document Focus and Focus Context
========================================

Paragraph 1: "...and operating system focus; this is referred to..."
"...which is the browser; when the browser..." "...achieving document
focus; once the document..."
Paragraph 2: "...persistent focus ring; when switching between..."
"...remain in their current state; for example, if a document..."
"...circumstances might require a mouse click; some elements might not..."
Whoa! Way too many semi-colons. These should all be periods followed by an
initial capital.

In DOMFocusIn, DOMFocusOut, the "Warning!" text should begin with a capital
letter.

5.2.3 Mouse Event Types
=======================

There is no section 5.2.3.1.

The last paragraph of this section seems a bit out of place:
"Implementations must maintain the current click count when generating
mouse events. This must be a non-negative integer indicating the number of
consecutive clicks of a pointing device button within a specific time. The
delay after which the count resets is specific to the environment
configuration."
There's no context for this paragraph. Where should this 'current click
count' value be stored? How is it accessed? Reading ahead reveals that it
is stored in UIEvent.detail and used by 'click', 'dblclick', 'mousedown',
and 'mouseup' events, but it would be nice if that was noted here.

5.2.3.2 Mouse Event Order
=========================

Figure 3 caption should be centered and start with a capital.

"Note: that mouseover/mouseout are only fired once..." initial cap

"Example: if the target element is removed from the DOM..." "...any default
activation events; however, the..." initial cap. semi-colon

In 'click', "Example: If a user mouses down on a text node child of a <p>
element which..." The <p> tag should be in a monospace font. 2 occurrences.

5.2.4 Wheel Event Types
=======================

In WebIDL Definition, the deltaX, deltaY and deltaZ field names do not line
up with the other field names.

5.2.5 Keyboard Event Types
==========================

"Example: the 'Q' key..." initial caps

Same problem with the other 5 "Example"s in the "Defined Constants" section.

In 'char' attribute, "Note the char attribute..." initial cap

In 'key' attribute, "Note the key attribute..." initial cap

5.2.5.1 Keyboard Event Order
============================

"The event target of a key event is the currently focused element which is
processing the keyboard activity; this is often an HTML input element or a
textual element which is editable, but may be an element defined by the
host language to accept keyboard input for non-text purposes, such as the
activation of a hotkey or trigger of some other behavior; if no suitable
element is in focus, the event target will be the root element."
This one sentence really should be three, with semi-colons becoming
periods. The Notes above and below this paragraph also use semi-colons
excessively.

Under 'keydown', each item in the bullet list should start with a capital.

In 'keydown', "Note: the keydown and keyup event..." initial cap needed.
Similar for the Note in 'keyup' and the Note and Warning in 'keypress'.

5.2.6.2 Handwriting Recognition Systems
=======================================

In 'compositionstart', "...without keyboard events. Some implemenations may
populate..." -> Spelling of 'implementations'

5.2.7 Mutation Events
=====================

"Note: none of the event types..." initial cap

The Warning boxes for DOMAttrModified, DOMCharacterDataModified,
DOMNodeInserted, DOMNodeInsertedIntoDocument, DOMNodeRemoved,
DOMNodeRemovedFromDocument and DOMSubtreeModified need an initial capital.

The Note boxes for DOMNodeInserted, DOMNodeRemoved and
DOMNodeRemovedFromDocument need an initial capital.

6.1.1 Key Legends
=================

"Note: the key legends for function keys..." initial capital

6.1.2 Keyboard Layout
=====================

"If the keyboard layout mapping is switched to a French mapping, pressing
the same key will produce the character 'a' ('\u0041', Latin Capital Letter
A)." The Unicode code point and name are incorrect. It should read: "...
will produce the character 'a' ('\u0061', Latin Small Letter A)."

6.1.2.2 Mobile Keypads
======================

"... in the range \u0061..\u007A to the number..." The Unicode values
should be formatted as '\u0061'..'\u007A' and highlighted in green for
consistency.

6.2.2 Modifier keys
===================

The difference between Examples 1 and 2 (which generate a character) and
Example 3 (which does not) can be made more apparent by adding the keypress
event to the first 2 examples.

6.2.3 Dead keys
===============

"Note: the MacOS and Linux operating systems use input methods to process
dead keys.)"  Initial capital and remove the trailing ')'

6.2.4.1 Input Method Editor mode keys
=====================================

"Note: keys with input method editor functions are not restricted to that
purpose, and can have other device- or implementation-specific purposes, as
well."

Initial caps. Remove the comma before the "as well".