[whatwg] A few editing suggestions for the HTML5 spec

[Ian Hickson]

On Sat, 14 Apr 2007, Geoffrey Garen wrote:
> 
> 1.4
> "when not qualified to explicitly refer"
> when not qualified explicitly to refer
> (split infinitive)

I prefer the current text.


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

Fixed.


> "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 if 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.

Fixed a bit, but not as much as you wanted.


> "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?

Fixed.


> 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.

This section was removed altogether.


> 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").

Added a note.


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

I don't understand the mistake.


> 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.

This section appears to be gone.


> 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.)

I don't think this change particularly helps. The example is relatively 
clear. Do you disagree?


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

I prefer the split version.

Cheers,
-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'