HTML5 Recommendation document review comments

i recently finished reading the HTML5 opus cover to cover.
it is very well done.  congratulations to the editor and
Thank You to everyone contributing.

here are some suggested editorial changes.  have double checked
them against Editor's Draft 21 December 2009.  please advise if
these should be posted as individual bugs, discussed/clarified
or whatever.  corrections or refinement are of course welcome.

========================================

Didn't see any document metadata via <meta> tags inside the
document itself.

Could also add a <link> entry providing a document icon, which is
helpful in tabbed browsers.

========================================

About 2 dozen minor Tidy warnings shown by Mozilla that could be
cleaned up.

========================================

General comment:  numerous elements and algorithms
describe state and state transitions.

It would be helpful to produce state transition diagrams for
each of these.  Additionally such diagrams will likely reveal
potential problems (state unreachability, transition ambiguity,
etc.) in the corresponding prose descriptions.

========================================
2.4.3 Keywords and enumerated attributes

"In addition, two default states can be given.
  The first is the <i>invalid value default</i>, the second
  is the <i>missing value default</i>."

The two italicized terms are not tagged as defined.

========================================
2.4.3 Keywords and enumerated attributes

"Note:  The empty string can be a valid keyword."

This statement doesn't make much sense since an
empty string is not a word per se, and so it can't be
a keyword either.  Further, an empty string isn't
allowed as an enumeration value in XML Schema
enumeration lists, so it is not clear how to
represent it in such a context.

Presumably an empty string might be a way of changing
the value of a nillable attribute which otherwise has
an originally defined default value.

Perhaps better phrasing is

"Note:  The empty string can be a valid attribute value
for determining state in this context."

========================================
3.1.4 DOM tree accessors

Should there be an inset box for

	document . html

similar to

	document . head

	etc.	

========================================
3.2.1 Semantics

change underlined _and_ to _or_ as follows:

"Authors must not use elements, attributes, _and_ attribute values
that are not permitted by this specification or other applicable
specifications."

becomes

"Authors must not use elements, attributes, _or_ attribute values
that are not permitted by this specification or other applicable
specifications."

========================================
3.2.3.3 The lang and xml:lang attributes

A few paragraphs appear to have extraneous <hr> elements
inserted before the <p>, which makes vertical spacing inconsistent.

========================================
3.2.3.5 The dir attribute

Displayed text directionality is explained for HTML but not for
SVG and MathML, which is somewhat inconsistent with some other
sections (such as discussion of document title in section 3.1.4,
DOM tree accessors).  Should further prose be added?

========================================
3.2.5.1.7 Interactive content

Wondering why svg and math elements are not listed under this section
for interactive content?  If so, add links to the list of relevant
elements.

========================================
3.2.5.2 Transparent content models

The use of "transparent" in this context is different than that used
for rendering SVG or other objects.  For X3D, a scene's background color
may be transparent in order to allow the HTML bgcolor to be shown.

Suggest considering another term for transparent (e.g. "replacable"
or somesuch) in the context of this section in order to avoid
name collisions and reader confusion.

========================================
3.2.5.3 Paragraphs

The following sentence is included:
"Conformance checkers may warn authors of cases where they have
paragraphs that overlap each other (this can happen with object,
video, audio, and canvas elements)."

Can this paragraph-overlap problem also happen with embed, svg and
math elements?

========================================
3.3 APIs in HTML documents

states
	Element.tagName and Node.nodeName
	These attributes must return element names converted to
	ASCII _uppercase_, regardless of the case with which they
	were created.

and then
	The canonical form of HTML markup is all-lowercase;

also in section 3.3 APIs in HTML documents
	when looking at HTML elements, the argument must first be
	converted to ASCII lowercase

This seems inconsistent.  Should the first _uppercase_ instead be lowercase?

========================================
4.4.3 The nav element

"Div element" should be plural in paragraph beginning

	Notice the div element being used

i.e. change to

	Notice the div elements being used

========================================
4.4.8 The header element

Is it appropriate to say something like

	The header can also be included at the top of each
	corresponding page when printing an HTML document.

========================================
4.4.9 The footer element

Similarly is it appropriate to say something like

	The footer can also be included at the bottom of each
	corresponding page when printing an HTML document.

========================================
4.5.2 The hr element

Append something like the following to opening sentence:

	The term hr refers to a horizontal rule, i.e.
	a line which runs across the page.

========================================
4.5.5 The blockquote element

This section ends with

	"Note:  Examples of how to represent a conversation are
	shown below; it is not appropriate to use the cite and
	blockquote elements for this purpose."

However no examples are found there.

========================================
4.7.5 Edits and lists

next-to-last line entry in example needs </li> appended, i.e.

change
	<li><ins>Purple</ins>
to
	<li><ins>Purple</ins></li>

========================================
9.1.1 The DOCTYPE

for paragraph

	Note:  In other words, <!DOCTYPE HTML SYSTEM "about:legacy-compat">
	or <!DOCTYPE HTML SYSTEM 'about:legacy-compat'>, case-insensitively
	except for the bit in quotes.

Change
	except for the bit in quotes.
to
	except for the bit in single or double quotes.

========================================
9.1.4 Character references

Draft document sayeth:

	"An ambiguous ampersand is a U+0026 AMPERSAND character (&)
	that is followed by some text other than a space character,
	a U+003C LESS-THAN SIGN character (<), or another
	U+0026 AMPERSAND character (&)."

probably should insert 2nd line as follows

	An ambiguous ampersand is a U+0026 AMPERSAND character (&)
	that is not a valid character reference, and

========================================
9.1.5 CDATA sections

A brief example would be helpful.

========================================

Again am happy to resubmit these as individual bugs if preferred for
precise issue tracking.  Again TIA for all review.

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br           brutzman@nps.edu
Watkins 270   MOVES Institute, Monterey CA 93943-5000 USA  work +1.831.656.2149
X3D, virtual worlds, underwater robots, XMSF  http://web.nps.navy.mil/~brutzman

Received on Sunday, 3 January 2010 01:55:27 UTC