Tree Lists

This specification has been replaced by Mallard 1.1.

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 can contain an optional title element followed by 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.

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_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
© 2008-2011 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard