Term Lists

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

Use the terms element to create a list of terms and associated definitions or descriptions. This type of list is often called a definition list or a variable list.

Notes

The terms element contains an optional info element, an optional title element, and one or more item elements. Each child item element can contain one or more title elements followed by general block content.
The terms 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 terms element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Create a simple definition list with a title:

<terms>
  <title>Selected Basic Block Elements</title>
  <item>
    <title><code>code</code></title>
    <p>Mark up a block of code or the contents of a file.</p>
  </item>
  <item>
    <title><code>example</code></title>
    <p>Mark up a group of block elements as being part of a single example.</p>
  </item>
  <item>
    <title><code>screen</code></title>
    <p>Mark up a textual user interface or an interactive shell session.</p>
  </item>
</terms>

Selected Basic Block Elements

code: Mark up a block of code or the contents of a file.
example: Mark up a group of block elements as being part of a single example.
screen: Mark up a textual user interface or an interactive shell session.

Create a definition list with multiple terms per entry:

<terms>
  <item>
    <title><code>comment</code></title>
    <title><code>quote</code></title>
    <p>Formal elements which allow a <code>cite</code> element.</p>
  </item>
  <item>
    <title><code>figure</code></title>
    <title><code>listing</code></title>
    <title><code>synopsis</code></title>
    <p>Formal elements which allow a <code>desc</code> element.</p>
  </item>
  <item>
    <title><code>note</code></title>
    <p>Formal elements which only allow a <code>title</code> element.</p>
  </item>
</terms>

comment
quote: Formal elements which allow a cite element.
figure
listing
synopsis: Formal elements which allow a desc element.
note: Formal elements which only allow a title element.

Processing Expectations

Term lists are displayed as block elements, with each child item displayed as some number of list items. When present, the title should be displayed in a way that makes it clear that it is the title of the list. Each title element of each list item is treated as a term, and is displayed as a block element. The remaining block content is then treated as the description and displayed as normal. The description blocks should be indented or otherwise styled to make their role clear.

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

Comparison to Other Formats

The terms element is similar to the variablelist element in DocBook. Like DocBook, Mallard groups terms with their corresponding descriptions. In DocBook, the description is wrapped with a listitem element inside the varlistentry element. In Mallard, the description is simply all of the block content except the title elements.

The terms element is similar to the dl element in DITA. Like DITA, Mallard groups terms with their corresponding descriptions. In DITA, each description is wrapped with a dd element inside the dlentry element. In Mallard, the description is simply all of the block content except the title elements. DITA allows you to specify headers for the terms and descriptions with the dlhead element. Mallard does not have this feature. If tabular headers are needed, use a table instead.

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

mal_block_terms = element terms {
  mal_block_terms_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_terms_item +
}
mal_block_terms_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_terms_item = element item {
  mal_block_terms_item_attr,
  mal_block_title +,
  mal_block_terms_item_content +
}
mal_block_terms_item_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_terms_item_content = mal_block