diff options
| -rw-r--r-- | doc/mallard/C/tenminutes.page | 99 | ||||
| -rw-r--r-- | doc/mallard/C/woscon.page | 31 | ||||
| -rw-r--r-- | sandbox/mallard/html/Makefile | 2 |
3 files changed, 96 insertions, 36 deletions
diff --git a/doc/mallard/C/tenminutes.page b/doc/mallard/C/tenminutes.page index c3cff85..16a356e 100644 --- a/doc/mallard/C/tenminutes.page +++ b/doc/mallard/C/tenminutes.page @@ -1,16 +1,17 @@ <page xmlns="http://projectmallard.org/1.0/" + xmlns:e="http://projectmallard.org/experimental/" type="topic" id="tenminutes"> <info> - <revision version="0.1" date="2007-02-21" status="stub"/> + <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</year> + <year>2008-2009</year> <name>Shaun McCance</name> </copyright> @@ -22,8 +23,98 @@ <title>Ten Minute Tour</title> <comment> - <cite date="2007-01-30"><name>Shaun McCance</name></cite> - <p>Add content</p> + <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> diff --git a/doc/mallard/C/woscon.page b/doc/mallard/C/woscon.page deleted file mode 100644 index 628d486..0000000 --- a/doc/mallard/C/woscon.page +++ /dev/null @@ -1,31 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="woscon"> - -<info> - <link type="guide" xref="index"/> - - <revision version="" date="" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - </credit> - <copyright> - <year>2009</year> - <name>Shaun McCance</name> - </copyright> - - <desc>I like maple syrup.</desc> -</info> - -<title>Writing Open Source Rocks!</title> - -<comment> - <cite href="mailto:shaunm@gnome.org">Shaun McCance</cite> - <p>Add content</p> -</comment> - -<p>Hello World</p> - -</page> diff --git a/sandbox/mallard/html/Makefile b/sandbox/mallard/html/Makefile index 4aff311..6319fc4 100644 --- a/sandbox/mallard/html/Makefile +++ b/sandbox/mallard/html/Makefile @@ -8,7 +8,7 @@ marks=watermark-blockquote-201C.png watermark-code.png all: $(pages) $(icons) $(marks) figures mallard.cache mallard.cache : $(specs) $(xslts) - echo '<cache xmlns="http://www.gnome.org/~shaunm/mallard">' > $@.in + echo '<cache xmlns="http://projectmallard.org/1.0/">' > $@.in for file in $(specs); do \ echo "<page href='$$file'/>" >> $@.in; \ done |