- From: Don Brutzman <brutzman@nps.edu>
- Date: Sat, 02 Jan 2010 17:54:44 -0800
- To: Ian Hickson <ian@hixie.ch>, public-html@w3.org
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