[whatwg] A few editing suggestions for the HTML5 spec

[Geoffrey Garen]

Hi folks.

I just read through the HTML5 spec for the first time. It looks  
great, and I appreciate all the hard work that everyone has done.

While reading through, I noticed a few edits that might improve  
clarity. I'm posting them here in a "take 'em or leave 'em" fashion  
-- take what you like, leave the rest.

Thanks,
Geoff

1.4
"when not qualified to explicitly refer"
when not qualified explicitly to refer
(split infinitive)

"or the node itself is there is none"
or the node itself if there is none
(typo)

"The term root element, when not qualified to explicitly refer to the  
document's root element, means the furthest ancestor element node of  
whatever node is being discussed, or the node itself is there is  
none. When the node is a part of the document, then that is indeed  
the document's root element. However, if the node is not currently  
part of the document tree, the root element will be an orphaned node."

I found this paragraph's wording vague and hard to understand. I  
would suggest instead:

The term root element, unless qualified explicitly to refer to the  
document's root element, means the furthest ancestor element node of  
the node under discussion, or, if the node under discussion has no  
ancestor element nodes, the node itself. When a node is a part of a  
document, its root element is the document's root element. Otherwise,  
its root element is an orphaned node.

"Some of the algorithms in this specification, for historical  
reasons, require the user agent to pause until some condition has  
been met. While a user agent is paused, it must ensure that no  
scripts execute (e.g. no event handlers, no timers, etc). User agents  
should remain responsive to user input while paused, however."

How should a user agent respond to user input that would cause an  
event handler to fire, like clicking on a button?

1.4.1

"Generally speaking, authors are discouraged from trying to use XML  
on the Web, because XML has much stricter syntax rules than the  
"HTML5" variant described above, and is relatively newer and  
therefore less mature."

"Stricter syntax rules" is often listed as an advantage of XML. If  
you're going to list it as a disadvantage, for credibility's sake, I  
think you should say something about why it's a disadvantage.

2.1.1

"The referrer attribute must return either the URI of the page which  
navigated the browsing context to the current document (if any), or  
the empty string (if there is no such originating page, or if the UA  
has been configured not to report referrers)."

It might help clarity to mention that a UA will intentionally hide  
referrers for security reasons (even the UA is not generally  
configured "not to report referrers").

3.3.3.1

"For instance, the script elements is allowed inside head elements"
For instance, the script element is allowed inside the head element
(typo)


3.3.2

"Text, embedded content, and elements that annotate the text without  
introducing structural grouping. For example: a, meter, img."

It would be nice if the examples followed the descriptions in order:  
[text], img, a.

3.12.4

"By emphasising the first word, the statement implies that the kind  
of animal under discussion is in question (maybe someone is asserting  
that dogs are cute):"
...implies that the kind of animal deserving to be called cute is in  
question...
(The first formation suggests that the speaker is questioning whether  
he/she is even talking about dogs and cats, not which one is cuter.)

8.2.1
"do not have to actually create a DOM Document object"
do not actually have to create a DOM Document object
(split infinitive)