Change Proposal: figure and details

Summary

The current HTML5 draft uses the dt and dd elements to markup the captions and content of the figure and details elements. This change proposal explains why the dt and dd elements are a poor choice for these purposes and proposes an alternative.

---

Rationale Against Using dt/dd for figure and details Elements

Backwards Compatibility

Due to IE's legacy parsing issues, the dt and dd elements create problems for authors attempting to use and style these elements. The simplest workaround (wrapping both figure and details in an extra div) that authors would need to apply to avoid these issues is not intuitive, as clearly demonstrated by the wide range of alternative solutions that were attempted prior to its discovery.

Legacy Cruft

This will likely lead to a lot of confusion among authors, at least initially, and ultimately end up becoming extraneous markup that authors just include without really understanding why, even after the current generation of browsers are long since dead.

We've seen this kind of problem before with authors, for example, frequently wrapping scripts with pseudo-HTML-comments initially intended to hide the script from what are now very ancient browsers, none of which have been in use for over a decade.

Styling Clashes

In addition to the aforementioned styling bug in IE, many existing stylesheets already include styles for the dt and dd elements, used in description lists (dl elements). Authors attempting to incorporate figure or details into their existing pages would have to take care to avoid unintended styling clashes caused by selectors that aren't specific enough. i.e. It's common for authors to simply use the selector as "dt" or "dd", rather than "dl>dt" and "dl>dd", as that is currently unnecessary. Authors will then have to adjust their styles, which could potentially cause unintended side affects to to the change in specificity of the selectors.

Default Styles

The default styles for dt and dd elements is not ideal for figures. As the dd element is usually indented with margin and/or padding, authors will usually be required to remove this with their own stylesheets, rather than being able to rely on more sensible defaults.

Structural Differences

Since authors are already familiar with the meanings and structure of dt and dd when used within dl, their very distinct meanings and structure when used within the figure and details may be confusing to authors.

The dl element may contain multiple groups of dt and dd elements, wheres within figure and details, each element may only be used once.

Within dl, a group must have one or more dt elements followed by one or more dd elements, whereas within figure, the elements may appear in any order.

Semantic Differences

For the figure element, it's not very intuitive to determine which of either dt or dd represents the caption and which represents the content such as an image. Some authors may interpret dd as being the description, which is what it means within dl, and thus assume that dd is meant for the caption, and the dt meant for the image or other content. However, the spec defines these with the opposite meanings, with the understanding the dt, or title, is a synonym for caption. Both alternatives points of view make some sense, but neither stands out as being obviously correct. This will likely lead to a lot of authors using these elements in reverse.

Unnecessary Elements

The dd element is completely unnecessary to distinguish it from the caption, which has its own element. This combined with the extraneous div required for IE compatibility adds two extra elements that are not logically needed. A previous iteration of the spec used the legend element for the caption, without any special wrapper just for the content. This model seems much more intuitive and required less markup to use, and thus easier to get right. Authors who do wish to have an extra wrapper around the content may use div if they choose, but should not be required to use it.

When there is no caption, using figure then requires authors to use 3 extra elements, where they should only need one:

<div> <!-- IE legacy workaround -->
  <figure>
    <dd><img src="image" alt="..."></dd>
  </figure>
</div>

This will be unappealing to authors who may, as a result of the complexity, opt not to use the figure element.

---

Proposal 1

The proposal is to restore the use of the legend element for marking up the captions within both figure and details elements.

Proposal 2

The proposal is to introduce a new c element for marking up the captions within both figure and details elements.

Proposal 3

The proposal is to introduce a new fcaption element for marking up the caption within figure, and a dlabel element for use within details.

Proposal 4

The proposal is to use the caption element within figure and the label element within details for marking up the captions.

Proposal 5

The proposal is to repurpose the h1 element for marking up the captions within both figure and details elements.

Proposal 6

The proposal is to introduce a caption attribute that may be used on an element within figure and details to denote the contents of that element as being the caption.

(caption attribute may be allowed on a limited set of elements, or maybe just p elements)