Block Descriptions

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

The desc element marks a short text description for formal block elements like figure. The description provided by desc is formatted as a caption for the formal element.

Notes

The desc element can contain a mixture of text and any general inline elements.
The desc element can occur in the formal block elements div, example, figure, listing, synopsis, and table.
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 desc element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The desc element can also be used in an informational context. See Page Descriptions for more information.

Examples

Use desc to provide a caption for a figure:

<figure>
  <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 is a question-mark-shaped duck head in a blue circle.

Use desc to provide a caption for a listing:

<listing>
  <desc>A first Mallard page</desc>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>]]></code>
</listing>

A first Mallard page

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>

More exaples can be found on the pages Figures, Listings, and Synopses.

Processing Expectations

The exact display of a description will depend on how the enclosing formal element is displayed. A description is a block of text that is displayed directly above or below the normal contents of the enclosing element.

A description should be displayed in a way that makes its role clear and which clearly distinguishes it from the normal block content of the enclosing element.

Comparison to Other Formats

The desc element is similar to the caption element in DocBook. DocBook captions may not appear in figure elements, although they may be provided for mediaobject elements within figure elements.

The desc element is similar to the desc element in DITA when used in a similar context. DITA desc elements may also be used to provide text descriptions for certain types of links.

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 block desc element. The namespace declarations for this definition are on the page Pages.

mal_block_desc = element desc {
  mal_block_desc_attr,
  mal_block_desc_inline
}
mal_block_desc_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_desc_inline = mal_inline