Re: Detailed review of Section 1. Introduction.

On Thu, 26 Jul 2007, Lee Kowalkowski wrote:
> 
> These are the comments from my detailed review of Section 1. 
> Introduction.  (http://www.w3.org/html/wg/html5/#introduction)
> 
> Nothing more than editorial in this section I'm afraid.
> 
> 1.1. Scope:
> "Browsers support many features that are considered [to be] very bad for 
> accessibility or [that are] otherwise inappropriate.  For example, the 
> blink element is clearly presentational and authors wishing to cause 
> text to blink should [instead] use CSS."  - I think this will read 
> better without the words in square brackets.

As I was reading this, before I got to the last bit you wrote, I was 
thinking to myself "what are the square brackets for? Oh, they're text I 
forgot to put in. Yeah he's right, it would read better with that text 
added." so I'm not sure I agree. :-)


> "The scope of this specification is not to..." -> "It is not the scope 
> of this specification to..."

I agree in principle but in this case I'd rather keep it more consistent 
with the two paragraphs before it.


> "In particular, hardware configuration software, image manipulation 
> tools..." - I don't understand the significance or relevance of 
> "hardware configuration software".  Unless "software" isn't supposed to 
> be in the sentence.  Or perhaps I just don't understand the objective of 
> this paragraph.  Maybe the concept in this paragraph isn't easy to 
> articulate.

For example, the Windows Devices Manager would not be in scope of HTML5. 
That's what that is trying to say.


> 1.2. Structure of this specification:
> "All [of] these features would be for naught if" - I found "for
> naught" quite an unusual term, "for nothing" is more popular, but
> perhaps "would be worthless" is more suitable.

"For naught" is a Britishism, and I'm British. Deal with it. :-)


> 1.3. Conformance requirements
> There are many unnumbered headings for the categories of user agents,
> perhaps there should be a "1.3.1 Conformance requirements for user
> agents", which contains those headings which are numbered accordingly.

That wouldn't work well because after the list (it's a <dl> with 
name/value pairs, not a bunch of sections) the text would no longer be in 
the same section as the text before the list.


> 1.3.1. Common conformance requirements for APIs exposed to JavaScript
> "Unless other specified" - I think this should be "Unless otherwise specified"

Fixed.


> 1.4. Terminology
> "The term HTML documents is sometimes used in contrast with XML
> documents to mean specifically documents that were parsed using an
> HTML parser" - I think the words "mean specifically" should be swapped
> around.

Fixed.

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

Received on Friday, 9 May 2008 06:18:28 UTC