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. Aesthetics may seem like a relatively unimportant factor; however, the desire to avoid introducing new elements that led to dt/dd being used is itself largely an aesthetic concern.

---

Proposal 1 (<figure><legend>...</legend>...</figure>; <details><legend>...</legend>...</details>)

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

Proposal 2 (<figure><c>...</c>...</figure>; <details><c>...</c>...</details>)

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

Proposal 3 (<figure><fcaption>...</fcaption>...</figure>; <details><dlabel>...</dlabel>...</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. Specifically, the proposal is to introduce a new fcaption element for marking up the caption within figure, and a dlabel element for use within details. The content portions of these elements (as opposed to the caption or label) would not have any special markup, they would be nested directly inside the figure or details element.

Additional Rationale

In addition to the rationale relative to the status quo in the spec, this proposal is better than some of the proposed alternatives.

Follows HTML Precedent for Structured Elements

Some HTML elements have relatively free content models, while others are "structured" - there are some or all child elements that have special meaning. Structured elements typically have helper elements that are specific to one element, or to a small family of related elements, to express their internal structure. Examples, from past versions of HTML, new in HTML5, and proposed for future versions of HTML:

• table has thead, tfoot, tbody, td, th, tr, caption, col and colgroup.
• ul, ol and menu have li.
• fieldset has legend.
• applet and object have param.
• video and audio have source.
• dl has dt and dd.
• select and datalist have option and optgroup.
• ruby has rp and rt.
• datagrid was proposed to have a number of specialized child elements.

In some cases (such as table or the list elements), the structured element can only have its specialized children. In other cases (fieldset, applet/object, or audio/video), the structured element can have relatively free content in addition to its specialized children.

Thus, when introducing new structured elements such as figure and details, the normal design pattern for HTML is to introduce new specialized child elements to represent their structure. It is not the norm to reuse a very common element such as "h1" to represent specialized structure in a certain context. It is not the norm to reuse specialized child elements in a way that differs from their established content and meaning, as with dt/dd or legend. And it is unprecedented to use an attribute that can occur on any element to represent specialized structure, as with the proposed caption attribute. Furthermore, details and figure are not particularly closely related in purpose. One is a UI control, the other is a representation of the structure of prose documents. So it does not make sense for them to share a specialized child element.

Applying a different design pattern for internal element structure to figure and details is likely to be confusing. The confusion of deviating from the usual HTML design pattern for this is likely to be greater than the cognitive cost of introducing no or fewer new elements.

Avoids Clunky or Inappropriate Names

The new element fltcap, suggested by another Change Proposal, appears confusing and mysterious. No one seems to get what it means on first reading. The expansion as "floating caption" seems confusing and semantically wrong. First, "floating caption" is not a very common term of art in publishing, but whenever it is used, it seems to refer to captions overlayed on top of the image, not figure captions in general. Furthermore, a details control does not in general have a "caption", floating or otherwise, rather it is a UI control and therefore is normally considered to have a "label".

The new element c is an extremely short and mysterious name. There is a limit to how many one-letter identifiers one can have in a language without rendering it unreadable or confusing, and they should be reserved for extremely common elements. Captions do not make the cut.

Reusing legend does not seem like a good semantic fit for either figure or details. While a figure's caption is sometimes called a legend, the term "legend" in this context more often refers to the key next to a map or chart explaining how to read various visual elements. A details element is a UI element and those aren't ordinarily referred to as having a legend.

h1 connotes "header", which is not quite right for either figure or details.

The caption attribute is good for figure, but not details. However, that proposal retains the dt/dd names for details. And those names remain clunky and non-obvious in the context of details (hard to remember which is which) and retain all of the general problems of using dt/dd for both elements.

"caption" and "label", or variations thereof, are the most semantically appropriate names for the caption and label respectively on figure and details.

Does Not Introduce Compatibility Problems

Reuse of almost any existing element in an unrelated context introduces compatibility problems, whether "hard" problems with parsing or behavior, or "soft" problems with pre-existing author styles. This Change Proposal uses brand new elements and thus avoids all these problems, unlike the use of dt/dd, legend, label, caption, or h1. All of those are known to have some lesser or greater technical issues.

Does Not Introduce Redundant Elements for the Content

Semantically, and for purposes of UA behavior, we only really need to distinguish the caption part of the element. There is no need to wrap the remaining body part with a special element. True, they can be handy as a styling hook, but authors who need that styling hook can always use

.

Details

This proposal includes the following specific changes:

1) Define a new element fcaption. Details would be approximately as follows:

Categories: none Contexts in which the element may be used: As the first or last child of a figure element. Content model: flow content Content attributes: global attributes DOM interface: HTMLElement Semantics: The fcaption element represents the caption of the figure that is its parent, if it has a parent that is a figure element.

2) Define a new element dlabel. Details would be as above, but replacing mentions of "figure" with "details".

3) Change figure as follows: New content model: "Flow content, optionally either preceded by or followed by an fcaption element." New caption definition: "The first fcaption element child of the element, if any, represents the caption of the figure element's contents. If there is no child fcaption element, then there is no caption." New content definition: "All child elements other than the first fcaption element, if there are any, represent the element's contents. If there are no child elements besides the first fcaption, then there are no contents. Update the examples appropriately. Update the suggested UA stylesheet in the Rendering section as appropriate.

4) Change details as follows:

 New content model: "One dlabel element, followed by Flow content."
 New summary definition: "The first dlabel element child of the element, if any, represents the summary of the details. If there is no child dlabel element, the user agent should provide its own label (e.g. "Details")."
 New details definition: "All child elements other than the first dlabel element, if there are any, represent the details. If there are no child elements besides the first dlabel, then there are no details.
 Update the examples appropriately.
 Update the suggested UA stylesheet in the Rendering section as appropriate.

Impact

This proposal would have a potential negative impact on authors: it would introduce two new elements relative to the current spec.

However, the positive impact is arguably greater. The new elements would be more readable, more intuitive, and more in line with the standard HTML design pattern for structured elements. Thus, despite the addition of more elements, the overall increase in cognitive load will be less. In addition, there is no need to use <div> or any other wonky workarounds to get it to work in legacy UAs.

The impact on implementations is trivial. fcaption and dlabel are trivial to implement, and the appearance and behavior can be mostly defined via stylesheet. This is not significantly more work than altering the rendering of dt and dd inside figure and details; in fact it may be less work in some implementations.

The impact on conformance checkers and authoring tools is also trivial; neither approach is easier or harder to validate or generate.

There is no direct impact on users either way.

Proposal 3b (<figure><figcaption>...</figcaption>...</figure>; <details><dsummary>...</dsummary>...</details>)

Same as proposal 3, but with the element names "figcaption" and "dsummary" respectively.

Reasoning: "figcaption" is more memorable. "dsummary" more accurately describes what the "label" of a <details> element is.

Proposal 4 (<figure><caption>...</caption>...</figure>; <details><label>...</label>...</details>)

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

CON: "caption" has significant unsolved parsing problems.

CON: "label" use in <details> would prevent the summary of a <details> from containing a labeled <progress> element, which is common, and would make the content model ambiguous (since the contents of a <details> can itself contain labels).

Proposal 5 (<figure><h1>...</h1>...</figure>; <details><h1>...</h1>...</details>)

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

CON: Styling issues in legacy UAs.

CON: Content model would be ambiguous.

Proposal 6 (<figure><p caption>...

...</figure>)

Summary

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

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 prose (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."
• "caption" added to the list of global attributes in the "Global Attributes" section. In its section it should contain roughly: "All HTML elements in the Flow Content category may have the caption content attribute set. The caption attribute is a boolean attribute. When caption is set on an element that is a child of a figure element, the first such element defines the caption for that figure element. It is invalid for a figure to have multiple child elements with the caption attribute set; in such a case, the first such element is the caption for the figure and the caption attribute is invalid and has no effect on subsequent elements. The caption attribute is invalid and has no effect on any element that is not a direct child of a figure element."

Impact

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

Proposal 7 (<figure><fcaption>...</fcaption>...</figure>; <details><dlabel>...</dlabel>...</details> or <figure><fcaption>...</fcaption><fbody>...</fbody></figure>; <details><dlabel>...</dlabel><dbody>...</dbody></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. Specifically, the proposal is to introduce a new fcaption element for marking up the caption within figure, and a dlabel element for use within details to replace dt. In addition, it proposes an optional fbody element for use inside figure, and an optional dbody element for use inside details, to mark up the content/body and replace dd.