Lists, Steps, and Terms Source

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="tutorial"
      id="list">

<info>
  <link type="guide" xref="index"/>

  <credit type="author copyright">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
    <years>2010</years>
  </credit>

  <include href="../../cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Add basic lists, step lists, term lists, and trees to your Mallard document.</desc>
</info>

<title>Lists, Steps, Terms, and Trees</title>

<note style="pmo-source">
<title>Learn by Example</title>
<p>This page was written in a Mallard extension format called Mallard Sites.
<link xref="list-src">Read the source markup</link> for this page to
learn Mallard from real-world examples.</p>
</note>

<p>Lists are a staple of technical documentation.  Readers can more easily scan
a page for what they need when information is presented in lists.  Mallard
provides various list elements that help you present information concisely.
In this tutorial, you will learn how to create a <link xref="#list">basic list</link>,
a <link xref="#steps">list of steps</link>, a <link xref="#terms">list of terms</link>,
and a <link xref="#tree">simple tree</link>.</p>

<section id="list">
<title>Basic Lists</title>

<p>You can create a basic bulleted list using the
<code xref="/1.1/mal_block_list">list</code> element.  Each list
item is contained in an <code>item</code> element.</p>

<example>
<code mime="application/xml"><![CDATA[
<list>
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
]]></code>
<list>
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
</example>

<note style="important">
<p>Notice that each <code>item</code> element contains a paragraph, marked up
with the <code xref="/1.1/mal_block_p">p</code> tag.  A list item
can contain multiple paragraphs or other block elements.  In Mallard, every
element contains either block or inline content, so even when you only use
a single line of text in a list item, you must use a paragraph.</p>
</note>

<p>A bulleted list is the default list type in Mallard.  You can specify
other list types with the <code>type</code> attribute on the <code>list</code>
element.  To create a numbered list, use the value <code>"numbered"</code>.</p>

<example>
<code mime="application/xml"><![CDATA[
<list type="numbered">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
]]></code>
<list type="numbered">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
</example>

<p>When you use the <code>"numbered"</code> type, processing tools will pick
an appropriate numbering system based on the language the page is written in.
You can also specify exactly which numbering system to use, or specify an
alternate type of glyph for bulleted lists.  The <code>type</code> attribute
accepts any <link href="http://www.w3.org/TR/css3-lists/">CSS3 list style</link>.</p>

<example>
<code mime="application/xml"><![CDATA[
<list type="lower-greek">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
]]></code>
<list type="lower-greek">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>
</example>

<note>
<p>When Mallard is converted to HTML, list style support may depend on
the CSS support in your web browser.</p>
</note>
</section>

<section id="steps">
<title>Step Lists</title>

<p>One of the most common uses for numbered lists in documentation is to
provide a list of instructions for a user to follow.  Although you can use
the <code>list</code> element to create a numbered list, Mallard provides
the <code xref="/1.1/mal_block_steps">steps</code> element to
list steps in a procedure.</p>

<example>
<code mime="application/xml"><![CDATA[
<steps>
  <item><p>Dig a hole 5cm deep.</p></item>
  <item><p>Place your magic beans in the hole.</p></item>
  <item><p>Fill the hole with clean dirt and pat it level.</p></item>
  <item><p>Water daily.</p></item>
</steps>
]]></code>
<steps>
  <item><p>Dig a hole 5cm deep.</p></item>
  <item><p>Place your magic beans in the hole.</p></item>
  <item><p>Fill the hole with clean dirt and pat it level.</p></item>
  <item><p>Water daily.</p></item>
</steps>
</example>

<p>Like the <code>list</code> element, the <code>steps</code> element takes any
number of <code>item</code> elements, and each <code>item</code> element must
contain a paragraph or other block content.  Step lists will be formatted so
that users can easily find them when looking through a page.</p>

</section>

<section id="terms">
<title>Term Lists</title>

<p>You can use the <code xref="/1.1/mal_block_terms">terms</code>
element to create a list of terms and descriptions in Mallard.  Use term lists
to create glossaries or to describe a list of configuration options.</p>

<example>
<code mime="application/xml"><![CDATA[
<terms>
  <item>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>
]]></code>
<terms>
  <item>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>
</example>

<p>Notice that each <code>item</code> element in a term list has a
<code xref="/1.1/mal_block_title">title</code> element to mark up
the actual term.  The description follows in a paragraph, or in any number of
other block elements.  You can also provide multiple terms for an item by
using multiple <code>title</code> elements.</p>

<example>
<code mime="application/xml"><![CDATA[
<terms>
  <item>
    <title>Fava beans</title>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>
]]></code>
<terms>
  <item>
    <title>Fava beans</title>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>
</example>

</section>

<section id="tree">
<title>Trees</title>

<p>Sometimes you need to show a hierarchy of items in documentation.  This is
useful, for example, to show a directory structure on a file system or a class
hierarchy in an object-oriented programming language.  Mallard provides the
<code xref="/1.1/mal_block_tree">tree</code> element to help you
create simple trees easily.</p>

<p>Use a tree to show some directories on a file system.</p>

<example>
<code mime="application/xml"><![CDATA[
<tree>
  <item>home
    <item>Drake
      <item>Documents</item>
    </item>
    <item>Wanda</item>
    <item>Wilbur
      <item>Pictures</item>
    </item>
  </item>
</tree>
]]></code>
<tree>
  <item>home
    <item>Drake
      <item>Documents</item>
    </item>
    <item>Wanda</item>
    <item>Wilbur
      <item>Pictures</item>
    </item>
  </item>
</tree>
</example>

<p>The <code>item</code> element works differently in trees than in the other
types of lists.  A tree item starts out with inline content, rather than block
content.  It can then contain other tree items that contain the child items.</p>

<p>The initial content doesn't have to be just text.  You can use any inline
markup before the child items.  For example, you can use the
<code xref="/1.1/mal_inline_file">file</code> element to indicate
that the items are file names.</p>

<example>
<code mime="application/xml"><![CDATA[
<tree>
  <item><file>home</file>
    <item><file>Drake</file>
      <item><file>Documents</file></item>
    </item>
    <item><file>Wanda</file></item>
    <item><file>Wilbur</file>
      <item><file>Pictures</file></item>
    </item>
  </item>
</tree>
]]></code>
<tree>
  <item><file>home</file>
    <item><file>Drake</file>
      <item><file>Documents</file></item>
    </item>
    <item><file>Wanda</file></item>
    <item><file>Wilbur</file>
      <item><file>Pictures</file></item>
    </item>
  </item>
</tree>
</example>

</section>

<section id="learnmore">
<title>Learn More</title>

<p>In this tutorial, you learned how to create four different types of lists
in Mallard.  You can do much more with lists in Mallard, such as add titles,
create nested lists, and use richer block content.  For more information, see
<link xref="/1.1/mal_block#lists"/> in the language specification.
The specification pages are full of examples to help you learn more.</p>
</section>

</page>