Over at 456BereaStreet, the ever-impressive Roger Johansson recently wrote an impassioned article about a perceived lack of support for semantic structure in HTML 5. He’s now had a chance to understand the issue more fully and has written a follow-up, Another Look at HTML 5, in which he explains his concerns in a more measured way.

All of his points are valid, but his call for more clarity in the specification really struck a chord with me:

Some of my previous worries and complaints are no doubt caused by me misreading the HTML 5 specification. My only excuse is that I find it very, very difficult to read since information that is only intended for browser developers is mixed with information that is important to authors (designers, developers, writers, CMS developers, etc.).

He’s right. Have you tried to read that thing? It’s anything but straightforward. I’ve had the same problem with the CSS Level 3 specifications as well; I’m reading through it to get information for CSS3.info, and it’s really hard going. Here’s an example from the Box Model module, the description for the display: compact declaration:

The effect depends on the intrinsic size of this element and on what comes after it. If the next element has a ‘display-role’ of ‘block’, and the intrinsic width of the compact element is less than or equal to the left margin of that block (resp. the right margin, if the block’s ‘direction’ is ‘rtl’), then the compact element is rendered in the left (right) margin of the block at its intrinsic size and baseline aligned with the first line box of the block. In all other cases the compact element is rendered as if its display-role was ‘block’.

Huh?

I’ve absolutely no idea what it does or why I should use it. I know these documents are written by technical people for technical people, but they must be made aware that end users are going to read it too. I fully support Roger’s call:

For authors to find the spec useful the parts that are relevant to them have to be cleanly separated, preferably into a separate document.