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

The use of extra div elements may 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. It is true that eventually UA stylesheets may have special rules for "figure > dt" and the like, but during the transition period it will be extra work to remove inappropriate default styles.

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.

Aesthetics

Aesthetics is not necessarily the sole or most important concern. However, many authors seem to find the novel use of dt and dd unpleasant to read. dt and dd are relatively obscure elements, they are very short abbreviations, and their meaning in context is unclear, especially in figure. In particular, the following markup seems mysterious and strikes many as ugly and unintuitive:

 <figure>
   <dd><img src="image" alt="..."></dd>
   <dt>A Pair of Cats</dd>
 </figure>

This seems to trigger a "yuck factor", and it would be wise to avoid that.

---

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

Summary

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.

Rationale

• This allows the most intuitive name to be used, without the problems caused by actually using <caption> as an element name.
• It roughly parallels the existing uses of attributes to tie together an element and some containing element with additional semantics, as seen in .
• It does not alter the existing semantics of the element it is applied to; a <ul caption> is still a <ul>, a <time caption> is still a <time>, etc.
• It forgoes the need for a 'wrapper' element when you just want to immediately apply a special element. For example, if you are putting photographs in a figure, with the only caption being the time it was taken, it would be best if you could simply put in the <time> without a wrapper. That is, <figure><img src=foo><time caption datetime=2010-01-11>January 11th, 2010</time></figure> is preferable to <figure><img src=foo><caption><time datetime=2010-01-11>January 11th, 2010</time></caption></figure>

Details

• Figure content model should be changed to "Flow Content".
• The third paragraph in the prose (explaining the use of the <dt> element) should be changed to roughly: "The first child element with the caption attribute, if any, represents the caption of the figure element's contents. If there is no child element with the caption attribute, then there is no caption."
• The fourth paragraph in the prsoe (explaining the use of the <dd> element) should be changed to roughly: "Any additional contents of the element beyond the caption (defined above), if any, represents the element's contents. If there are no additional contents, then there are no contents."

Impact

Easy denotation of figure captions, without any compatibility hacks that may persist long into the future.