[whatwg] A few editing suggestions for the HTML5 spec
Geoffrey Garen
ggaren at apple.com
Sat Apr 14 15:14:34 PDT 2007
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)
More information about the whatwg
mailing list