[whatwg] example of serialization problems

[Shelley Powers]

Review of HTML5 document:

Here's a good example of a potential point of confusion for readers of 
the spec when it comes to serialization:

In section 4.5.8 you introduce the ul element, and then demonstrate it 
with a several child li elements, each of which is shown with an HTML 
serialization.

In second 4.5.9, you introduce the li element, and then demonstrate the 
li element using a serialization approach that would work with both 
XHTML and HTML serializations.

And still later, in section 4.5.13.1, you again demonstrate li elements 
using only the HTML serialization format.

In all of this is an implicit assumption of the capabilities of your 
audience, that they understand the differences between the two. Yet, 
this isn't stated as a prereq for the audience of the document. In fact, 
you state that a familiarity with XML is helpful, but not required. And 
as far as I've been able to see, though I may have missed it, 
discussions about closing tags doesn't take place until section 8.

My suggestion would be to include both HTML and XHTML serializations, 
carefully differentiating between the two. Or to provide separate 
documents detailing the elements and their serialized form, HTML version 
and XHTML version, if you want to inter-mix model and serialization 
technique.

As for Section 8, that really is for user agent developers, only. 
Seriously, I doubt you expect typical web developers or designers to get 
much from this section. I would almost expect this to be a separate 
document. What would be helpful is to bring this section up one level in 
complexity, specifically focused at web developers/designers.

More later

Shelley