Today it occurred me to have a look at the DITA Architecture Specification source to see how the people behind the spec would tag a list; as some of you know, this was the subject of my recent blog entry. There are a number of lists in that spec, many with introductory paragraphs, so it’s a pretty obvious way to find out, right? Well, after the examples in that spec, maybe.

Anyway, this is how they do it:

<p>Introductory para:
<ul>
<li>Item</li>
<li>Item</li>
</ul>
</p>

This was one of my guesses, and I have to say that it’s better than any of the alternatives I could come up with. It’s not good markup, though, in my opinion, as it says that semantically, a paragraph is sort of a block-level superclass, a do-it-all and one that you must use if you need that introduction.

But then, why limit yourself to lists? Why aren’t notes tagged like that? Or definition lists, or images, or tables? Think about it. Doesn’t this feel just a little bit like a cop-out to you? It does to me. It feels like the author realised that he needed that wrapper but there was nothing he could cling to, other than this construction.

I’m not saying that my way is the only way (obviously it’s not) but this bothers me because it muddies the semantic waters.