Tree Lists

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

Use the tree element to create a hierarchical tree. While conceptually similar to nested list elements, trees offer a simple way to display common hierarchies such as class inheritance or directory layouts.

Notes

The tree element contains an optional info element, an optional title element, and one or more item elements. Each child item element can contain a mixture of text and any general inline elements, followed by zero or more nested item elements.
The tree 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 following style hints are recommended:

lines

draw lines to show the hierarchy
The tree element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use a tree to outline a class hierarchy inside a synopsis element:

<synopsis>
  <tree>
    <item>
      <code>GtkBin</code>
      <item>
        <code>GtkButton</code>
        <item><code>GtkToggleButton</code></item>
        <item><code>GtkColorButton</code></item>
        <item><code>GtkFontButton</code></item>
        <item><code>GtkLinkButton</code></item>
        <item><code>GtkOptionMenu</code></item>
        <item><code>GtkScaleButton</code></item>
      </item>
    </item>
  </tree>
</synopsis>

GtkBin
- GtkButton
  - GtkToggleButton
  - GtkColorButton
  - GtkFontButton
  - GtkLinkButton
  - GtkOptionMenu
  - GtkScaleButton

Use the lines style hint to visually show the tree structure:

<tree style="lines">
  <item>
    Anatinae (dabbling ducks)
    <item>
      Anas
      <item>Baikal Teal</item>
      <item>Wigeons</item>
      <item>Mallard</item>
    </item>
    <item>Lophonetta</item>
    <item>Speculanas</item>
  </item>
  <item>
    Anthyinae (diving ducks)
    <item>Aythya</item>
    <item>Netta</item>
  </item>
  <item>Dendrocygninae (whistling ducks)</item>
</tree>

Anatinae (dabbling ducks)
-     ├ Anas
  -     │    ├ Baikal Teal
  -     │    ├ Wigeons
  -     │    └ Mallard
-     ├ Lophonetta
-     └ Speculanas
Anthyinae (diving ducks)
-     ├ Aythya
-     └ Netta
Dendrocygninae (whistling ducks)

Processing Expectations

Tree lists are display as block elements. Each child item has its leading inline content displayed in a single block and any nested item elements displayed as blocks in turn. Successive levels of nesting should yield more indentation, though this may vary based on style hints or other factors. By default, there should be little vertical spacing between items; trees are compact. No bullets, icons, or other marks are expected to precede items, although they may be used for certain style hints.

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

Comparison to Other Formats

The tree element has no direct equivalent in DocBook or DITA. In DocBook, a similar effect can be accomplished with nested itemizedlist elements by setting the spacing attribute to "compact" and setting the mark attribute to a value understood by your processing tool to remove bullets. In DITA, a similar effect can be accomplished with nested ul elements by setting the compact attribute to "yes" and instructing your processing tool to omit bullets. For non-hierarchical lists, the tree element functions similarly to the sl 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 tree element. The namespace declarations for this definition are on the page Pages.

mal_block_tree = element tree {
  mal_block_tree_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_tree_item +
}
mal_block_tree_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_tree_item = element item {
  mal_block_tree_item_attr,
  mal_block_tree_item_inline,
  mal_block_tree_item *
}
mal_block_tree_item_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_tree_item_inline = mal_inline