Basic Lists

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

Use the list element to create a basic bulleted or numbered list. By default, lists are unordered, and list items are marked with a bullet or other glyph. You can select various numbering systems using the type attribute. If you need a numbered list to enumerate steps the reader should perform, use the steps element.

Notes

The list element contains an optional info element, an optional title element, and one or more item elements. Each child item element can contain general block content.
The list element can occur in any general block context, including inside pages, sections, and certain block elements.
The type attribute allows you to select the list type, which affects the markers used for each list item. Allowed values are those from the CSS list-style-type property. Additionally, the value of "numbered" can be used to select a numbered list type appropriate for the page's language.
If no type attribute is present, it is assumed to be a glyph type such as "disc" or "circle". That is, lists default to bulleted lists.
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 list element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Create a basic unordered list:

<list>
  <item><p><code>GTK_MESSAGE_INFO</code></p></item>
  <item><p><code>GTK_MESSAGE_WARNING</code></p></item>
  <item><p><code>GTK_MESSAGE_QUESTION</code></p></item>
  <item><p><code>GTK_MESSAGE_ERROR</code></p></item>
  <item><p><code>GTK_MESSAGE_OTHER</code></p></item>
</list>

GTK_MESSAGE_INFO
GTK_MESSAGE_WARNING
GTK_MESSAGE_QUESTION
GTK_MESSAGE_ERROR
GTK_MESSAGE_OTHER

Create an unordered list with a title:

<list>
  <title>Message Types</title>
  <item><p><code>GTK_MESSAGE_INFO</code></p></item>
  <item><p><code>GTK_MESSAGE_WARNING</code></p></item>
  <item><p><code>GTK_MESSAGE_QUESTION</code></p></item>
  <item><p><code>GTK_MESSAGE_ERROR</code></p></item>
  <item><p><code>GTK_MESSAGE_OTHER</code></p></item>
</list>

Message Types

GTK_MESSAGE_INFO
GTK_MESSAGE_WARNING
GTK_MESSAGE_QUESTION
GTK_MESSAGE_ERROR
GTK_MESSAGE_OTHER

Create a simple numbered list:

<list type="numbered">
  <item><p>First</p></item>
  <item><p>Second</p></item>
  <item><p>Third</p></item>
</list>

First
Second
Third

Create a numbered list with Roman numerals:

<list type="upper-roman">
  <item><p>First</p></item>
  <item><p>Second</p></item>
  <item><p>Third</p></item>
</list>

First
Second
Third

Processing Expectations

Lists are displayed as block elements, with each child item displayed as a list item. When present, the title should be displayed in a way that makes it clear that it is the title of the list. List items are interpreted in the same way as li elements in HTML, except that the item element only allows block-level child content.

Item markers are taken from the type attribute, which is either a valid value of the CSS list-style-type property, or the special value "numbered". When the "numbered" type is used, a numeric marker type is chosen that is appropriate for the language of the page. The default numeric marker type per language may vary between implementations.

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

Comparison to Other Formats

The list element combines the functionality of the itemizedlist and orderedlist elements in DocBook. DocBook allows leading block-level content in its list elements. This is not allowed in Mallard, though an optional title element is allowed. DocBook allows you to override the bullet or numbering type on each list item. Mallard does not allow this.

The list element combines the functionality of the ol and ul elements in DITA. DITA allows you to mix block and inline content in list items. Mallard list items may only contain block content. Mallard allows an optional title element.

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

mal_block_list = element list {
  mal_block_list_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_list_item +
}
mal_block_list_attr = (
  attribute type { xsd:NMTOKEN } ?,
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_list_item = element item {
  mal_block_list_item_attr,
  mal_block_list_item_content +
}
mal_block_list_item_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_list_item_content = mal_block