<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:e="http://projectmallard.org/experimental/" type="topic" id="tenminutes">

<info>
  <revision version="0.1" date="2009-06-16" status="incomplete"/>

  <credit type="author">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
  </credit>
  <copyright>
    <year>2008-2009</year>
    <name>Shaun McCance</name>
  </copyright>

  <include xmlns="http://www.w3.org/2001/XInclude" href="legal.xml"/>

  <desc>Create a multiple-page document in only ten minutes.</desc>
</info>

<title>Ten Minute Tour</title>

<comment>
  <cite date="2009-06-16">shaunm</cite>
  <p>This is draft material.  I'm not happy with the tone yet.</p>
</comment>

<p>In this page, we will present how to create a simple multiple-page Mallard
document.  We will create a document for the fictitious <app>Beanstalk</app>
application, which allows you to plant magic beans.</p>

<p>A Mallard document is composed of multiple independent pages.
<link xref="mal_page#topic">Topic pages</link> present some piece of information
to the reader.  This might be a tutorial, a conceptual overview, reference material,
or any other type of written content.  <link xref="mal_page#guide">Guide pages</link>
serve as the navigational glue between topics, helping readers find and explore
content.</p>

<p>We can begin making a Mallard document by writing a front page for our
document.  Generally, the front page of any document will be a guide page,
as its purpose is to help users navigate to other content.  In Mallard, the
front page of any document is named <file>index.page</file>.</p>

<listing>
  <title><file>index.page</file></title>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
<title>Beanstalk Help</title>
</page>]]></code>
</listing>

<p>This simple example is a valid Mallard guide page.  Taken alone, it is
also a valid Mallard document, although it's rather useless.  We can add
another page to the document by creating a new page file.</p>

<listing>
  <title><file>planting.page</file></title>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
<title>Planting Beans</title>
</page>]]></code>
</listing>

<p>Notice that we have set the <code>type</code> attribute to <code>"guide"</code>
in <file>index.page</file> and to <code>"topic"</code> in <file>planting.page</file>.
This specifies that <file>index.page</file> is a guide page, which will allow it to
have automatic links to other pages.  Currently, we have two standalone pages without
interlinking.  We can have <file>index.page</file> link to <file>planting.page</file>.</p>

<listing>
  <title><file>planting.page</file></title>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
]]><e:hi><![CDATA[<info>
  <link type="guide" xref="index"/>
</info>]]></e:hi><![CDATA[
<title>Planting Beans</title>
</page>]]></code>
</listing>

<comment>
  <cite date="2009-06-16">shaunm</cite>
  <p>Explain the linking and introduce the next example.</p>
</comment>

<listing>
  <title><file>planting.page</file></title>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
<info>
  <link type="guide" xref="index"/>
</info>
<title>Planting Beans</title>]]><e:hi><![CDATA[
<p>By the end of this page, you will be able to plant your magic
beans and nurture them into a bean sprout.</p>
<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>]]></e:hi><![CDATA[
</page>]]></code>
</listing>

<comment>
  <cite date="2009-06-16">shaunm</cite>
  <p>Fill in more content.</p>
</comment>

</page>
