My Other Christmas Present Is a Definition List

Last year, I looked at how the markup for tag clouds was generally terrible. I thought this year I would look not at a method of marking up a common module, but instead just at a simple part of HTML and how it generally gets abused.

No, not tables. Definition lists. Ah, definition lists. Often used but rarely understood.

Examining the definition of definitions

To start with, let’s see what the HTML spec has to say about them.

Definition lists vary only slightly from other types of lists in that list items consist of two parts: a term and a description.

The canonical example of a definition list is a dictionary. Words can have multiple descriptions (even the word definition has at least five). Also, many terms can share a single definition (for example, the word colour can also be spelt color, but they have the same definition).

Excellent, we can all grasp that. But it very quickly starts to fall apart. Even in the HTML specification the definition list is mis-used.

Another application of DL, for example, is for marking up dialogues, with each DT naming a speaker, and each DD containing his or her words.

Wrong. Completely and utterly wrong. This is the biggest flaw in the HTML spec, along with dropping support for the start attribute on ordered lists. “Why?”, you may ask. Let me give you an example from Romeo and Juliet, act 2, scene 2.

<dt>Juliet</dt>
	<dd>Romeo!</dd>
<dt>Romeo</dt>
	<dd>My niesse?</dd>
<dt>Juliet</dt>
	<dd>At what o'clock tomorrow shall I send to thee?</dd>
<dt>Romeo</dt>
	<dd>At the hour of nine.</dd>

Now, the problem here is that a given definition can have multiple descriptions (the DD). Really the dialog “descriptions” should be rolled up under the terms, like so:

<dt>Juliet</dt>
	<dd>Romeo!</dd>
	<dd>At what o'clock tomorrow shall I send to thee?</dd>
<dt>Romeo</dt>
	<dd>My niesse?</dd>
	<dd>At the hour of nine.</dd>

Suddenly the play won’t make anywhere near as much sense. (If it’s anything, the correct markup for a play is an ordered list of CITE and BLOCKQUOTE elements.)

This is the first part of the problem. That simple example has turned definition lists in everyone’s mind from pure definitions to more along the lines of a list with pre-configured heading(s) and text(s).

Screen reader, enter stage left.

In many screen readers, a simple definition list would be read out as “definition term equals definition description”. So in our play excerpt, Juliet equals Romeo! That’s not right, either. But this also leads a lot of people astray with definition lists to believing that they are useful for key/value pairs.

Behaviour and convention

The WHAT-WG have noticed the common mis-use of the DL, and have codified it into the new spec. In the HTML5 draft, a definition list is no longer a definition list.

The dl element introduces an unordered association list consisting of zero or more name-value groups (a description list). Each group must consist of one or more names (dt elements) followed by one or more values (dd elements).

They also note that the “dl element is inappropriate for marking up dialogue, since dialogue is ordered”. So for that example they have created a DIALOG (sic) element.

Strange, then, that they keep DL as-is but instead refer to it an “association list”. They have not created a new AL element, and kept DL for the original purpose. They have chosen not to correct the usage or to create a new opportunity for increased specificity in our HTML, but to “pave the cowpath” of convention.

How to use a definition list

Given that everyone else is using a DL incorrectly, should we? Well, if they all jumped off a bridge, would you too? No, of course you wouldn’t. We don’t have HTML5 yet, so we’re stuck with the existing semantics of HTML4 and XHTML1. Which means that:

• Listing dialogue is not defining anything.
• Listing the attributes of a piece of hardware (resolution = 1600×1200) is illustrating sample values, not defining anything (however, stating what ‘resolution’ actually means in this context would be a definition).
• Listing the cast and crew of a given movie is not defining the people involved in making movies. (Stuart Gordon may have been the director of Space Truckers, but that by no means makes him the true definition of a director.)
• A menu of navigation items is simply a nested ordered or unordered list of links, not a definition list.
• Applying styling handles to form labels and elements is not a good use for a definition list.

And so on.

Living by the specification, a definition list should be used for term definitions – glossaries, lexicons and dictionaries – only.

Anything else is a crime against markup.