Step Lists

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

Use the steps element to create a list of steps the reader should follow. The steps element is structurally similar to the list element. Marking the list as instructions to the reader allows special display rules to be applied. If you want a numbered list that is not a procedure, use the list element with the type attribute set to "numbered" instead.

Notes

The steps 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 steps 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 steps element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Create a simple procedure of steps for the reader to follow:

<steps>
  <title>Planting Magic Beans</title>
  <item><p>Dig a hole 10cm deep.</p></item>
  <item><p>Place magic beans in the hole.</p></item>
  <item><p>Fill hole with fertilized soil.</p></item>
  <item><p>Water frequently.</p></item>
</steps>

Planting Magic Beans

Dig a hole 10cm deep.
Place magic beans in the hole.
Fill hole with fertilized soil.
Water frequently.

Create steps with a nested list and a nested step list:

<steps>
  <title>Planting Magic Beans</title>
  <item>
    <p>Perform one of the following:</p>
    <list>
      <item><p>Dig a whole 10cm deep.</p></item>
      <item><p>Find a whole 10cm deep.</p></item>
    </list>
  </item>
  <item><p>Place magic beans in the hole.</p></item>
  <item><p>Fill hole with fertilized soil.</p></item>
  <item>
    <p>Water frequently with the following steps:</p>
    <steps>
      <item><p>Fill watering can with water.</p></item>
      <item><p>Pour water onto spot where beans were planted.</p></item>
    </steps>
  </item>
</steps>

Planting Magic Beans

Perform one of the following:
- Dig a whole 10cm deep.
- Find a whole 10cm deep.
Place magic beans in the hole.
Fill hole with fertilized soil.
Water frequently with the following steps:
1. Fill watering can with water.
2. Pour water onto spot where beans were planted.

Processing Expectations

Step lists are displayed as block elements, with each child item displayed as a numbered list item. When present, the title element 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.

Step lists should have a background color, border, or other styling effect to clearly differentiate them from basic numbered lists. Special styling allows readers to skim pages more easily.

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

Comparison to Other Formats

The steps element is similar to the procedure element in DocBook. Mallard uses the common item element instead of a dedicated step element. DocBook allows leading block-level content in its procedures. This is not allowed in Mallard, though an optional title element is allowed. DocBook provides explicit substeps and stepalternatives elements. Mallard has no equivalent. For substeps, use nested steps elements. For alternatives, use a basic list with introductory text.

The steps element is similar to the steps element in DITA. Mallard step lists can be used in any block context, and not just in a dedicated task topic. Mallard uses the common item element instead of a dedicated step element. DITA provides various elements to mark up instructions, substeps, examples, results, and lists or tables of choices. Mallard does not provide specific markup for these. Use common elements like paragraphs, basic lists, and tables instead, possibly with leading text to explain their role to the reader.

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

mal_block_steps = element steps {
  mal_block_steps_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_steps_item +
}
mal_block_steps_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_steps_item = element item {
  mal_block_steps_item_attr,
  mal_block_steps_item_content +
}
mal_block_steps_item_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_steps_item_content = mal_block