Figures

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the figure element to provide a title or caption for a multimedia object or other block object. To provide a title for the contents of a file, such as a code block, use the listing element instead.

Notes

The figure element contains an optional info element, an optional title element, an optional desc element, and any general block content.
The figure element can occur in any general block context, including inside pages, sections, and certain block elements.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The figure element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use figure to provide a title and caption for an image:

<figure>
  <title>The Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a blue circle.</desc>
  <media type="image" mime="image/png" src="mallard-logo.png"/>
</figure>

The Mallard Logo

The Mallard logo is a question-mark-shaped duck head in a blue circle.

Processing Expectations

Figures are displayed as block elements, with each of their child elements interpreted as block elements. When present, the title and description should be displayed in a way that makes their respective roles clear.

The optional info element can provide metadata for the figure, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

The figure element is similar to the figure element in DocBook. DocBook only provides a title for figures, whereas Mallard distinguishes between a title and a caption.

The figure element is similar to the fig element in DITA.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the figure element. The namespace declarations for this definition are on the page Pages.

mal_block_figure = element figure {
  mal_block_figure_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_desc ?,
  mal_block_figure_content +
}
mal_block_figure_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_figure_content = mal_block