Re: [whatwg] example of serialization problems

(-whatwg to reduce cross-posting)

On Sat, 2 May 2009, Shelley Powers wrote:
> 
> 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.

All of these examples would only work in text/html -- they are all missing 
namespaces, for instance.

As far as I'm aware, all the examples are text/html examples except where 
explicitly introduced as XML examples.

(It's not practical in many cases to make the HTML examples non-well- 
formed XML, so I don't propose to go and make sure that none of the HTML 
examples can be misinterpreted as XML.)


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

If XHTML were actually widely used in practice, I would agree, but in 
practice almost all the readers of the spec will be using HTML, so I think 
focusing on having HTML examples is probably good enough.


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

I don't really see how this would work -- we wouldn't want to duplicate 
the information in multiple specs, that would just be a maintenance 
nightmare.


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

Do you mean section 9.1 Writing HTML documents, or section 9.2 Parsing 
HTML documents, or both?

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

Received on Friday, 5 June 2009 22:47:02 UTC