doc/en/xml-guide.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.30 2004/05/09 12:47:28 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/xml-guide.xml">
<title>Gentoo Linux XML Guide</title>

<author title="Author">
  <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
</author>
<author title="Author"><!-- zhen@gentoo.org -->
  John P. Davis
</author>
<author title="Editor">
  <mail link="peesh@gentoo.org">Jorge Paulo</mail>
</author>
<author title="Editor">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>

<abstract>
This guide shows you how to compose web documentation using the new lightweight
Gentoo GuideXML syntax.  This syntax is the official format for Gentoo Linux 
documentation, and this document itself was created using GuideXML.  This guide
assumes a basic working knowledge of XML and HTML.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
<license/>

<version>2.10</version>
<date>May 09, 2004</date>

<chapter>
<title>Guide basics</title>
<section>
<title>Guide XML design goals</title>
<body>

<p>
The guide XML syntax is lightweight yet expressive, so that it is easy to
learn yet also provides all the features we need for the creation of web
documentation.  The number of tags is kept to a minimum -- just those we need.
This makes it easy to transform guide into other formats, such as DocBook
XML/SGML or web-ready HTML.
</p>

<p>
The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
documents.
</p>

</body>
</section>
<section>
<title>Further Resources</title>
<body>

<p>
If you are planning on contributing documentation to Gentoo, or you want to test
GuideXML, please read the <uri
link="http://www.gentoo.org/doc/en/doc-tipsntricks.xml">Tips and Tricks</uri>
which contains tips and tricks for documentation development.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Guide XML</title>
<section>
<title>Basic structure</title>
<body>

<p>
Now that you know how to transform guide XML, you're ready to start learning
the GuideXML syntax.  We'll start with the the initial tags used in a guide
XML document:
</p>

<pre caption="The initial part of a guide XML document">
&lt;?xml version='1.0' encoding="UTF-8"?&gt;
&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
&lt;guide link="relative_link_to_your_guide"&gt;
&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
&lt;author title="<i>Chief Architect</i>"&gt;
  &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt;
&lt;/author&gt;
&lt;author title="<i>Editor</i>"&gt;
  &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt;
&lt;/author&gt;

&lt;abstract&gt;
<i>This guide shows you how to compose web documentation using
our new lightweight Gentoo GuideXML syntax.  This syntax is the official
format for Gentoo Linux web documentation, and this document itself was created
using GuideXML.</i>
&lt;/abstract&gt;

&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
&lt;!-- See http://creativecommons.org/licenses/by-sa/1.0 --&gt;
&lt;license/&gt;

&lt;version&gt;<i>1.0</i>&lt;/version&gt;
&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
</pre>

<p>
On the first, line, we see the requisite tag that identifies this as an XML
document.  Following it, there's a <c>&lt;guide&gt;</c> tag  -- the entire
guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
guide document.
</p>

<p>
Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
about the various authors of the document.  Each <c>&lt;author&gt;</c> tag
allows for an optional <c>title=</c> element, used to specify the author's
relationship to the document (author, co-author, editor, etc.).  In this
particular example, the authors' names are enclosed in another tag -- a
<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
person.  The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
more than one <c>&lt;author&gt;</c> element is required per guide document.
</p>

<p>
Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
current version number, and the current version date (in DD MMM YYYY format)
respectively.  This rounds out the tags that should appear at the beginning of
a guide document.  Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
tags, these tags shouldn't appear anywhere else except immediately inside the
<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
required) that these tags appear before the content of the document.  
</p>

<p>
Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative 
Commons - Attribution / Share Alike</uri> license as required by the <uri 
link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
</p>

</body>
</section>
<section>
<title>Chapters and sections</title>
<body>

<p>
Once the initial tags have been specified, you're ready to start adding
the structural elements of the document.  Guide documents are divided into
chapters, and each chapter can hold one or more sections.  Every chapter
and section has a title.  Here's an example chapter with a single section,
consisting of a paragraph.  If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
(if minimal) guide document:
</p>

<pre>
&lt;chapter&gt;
&lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
&lt;section&gt;
&lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
&lt;body&gt;

&lt;p&gt;
<i>This is the actual text content of my section.</i>
&lt;/p&gt;

&lt;/body&gt;
&lt;/section&gt;
&lt;/chapter&gt;
</pre>

<p>
Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
element to the <c>&lt;chapter&gt;</c> element.  Then, I created a section by
adding a <c>&lt;section&gt;</c> element.  If you look inside the
<c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
<c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>.  While the <c>&lt;title&gt;</c>
is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
content of this particular section.  We'll look at the tags that are allowed
inside a <c>&lt;body&gt;</c> element in a bit. 
</p>

<note>
A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c> 
elements, and a <c>&lt;chapter&gt;</c> can contain multiple 
<c>&lt;section&gt;</c> elements.  However, a <c>&lt;section&gt;</c>
element can only contain one <c>&lt;body&gt;</c> element.  
</note>

</body>
</section>
<section>
<title>An example &lt;body&gt;</title>
<body>

<p>
Now, it's time to learn how to mark up actual content.  Here's the XML code for an example <c>&lt;body&gt;</c> element:
</p>

<pre>
&lt;p&gt;
This is a paragraph.  &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
Type &lt;c&gt;ls&lt;/c&gt; if you feel like it.  I &lt;e&gt;really&lt;/e&gt; want to go to sleep now.
&lt;/p&gt;

&lt;pre&gt;
This is text output or code.
# &lt;i&gt;this is user input&lt;/i&gt;

Make HTML/XML easier to read by using selective emphasis:
&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;

&lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
&lt;/pre&gt;

&lt;note&gt;
This is a note.
&lt;/note&gt;

&lt;warn&gt;
This is a warning.
&lt;/warn&gt;

&lt;impo&gt;
This is important.
&lt;/impo&gt;
</pre>

<p>
Now, here's how this <c>&lt;body&gt;</c> element is rendered:
</p>

<p>
This is a paragraph.  <path>/etc/passwd</path> is a file.
<uri>http://www.gentoo.org</uri> is my favorite website.
Type <c>ls</c> if you feel like it.  I <e>really</e> want to go to sleep now.
</p>

<pre>
This is text output or code.
# <i>this is user input</i>

Make HTML/XML easier to read by using selective emphasis:
&lt;foo&gt;<i>bar</i>&lt;/foo&gt;

<codenote>This is how to insert an inline note into the code block</codenote>
</pre>

<note>
This is a note.
</note>

<warn>
This is a warning.
</warn>

<impo>
This is important.
</impo>

</body>
</section>
<section>
<title>The &lt;body&gt; tags</title>
<body>

<p>
We introduced a lot of new tags in the previous section -- here's what you
need to know.  The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
these are the only tags that should appear immediately inside a
<c>&lt;body&gt;</c> element.  Another thing -- these tags <e>should not</e> be
stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
<c>&lt;p&gt;</c> element.  As you might guess, the <c>&lt;pre&gt;</c> element
preserves its whitespace exactly, making it well-suited for code excerpts. 
You can also name the <c>&lt;pre&gt;</c> tag:
</p>

<pre caption = "Named &lt;pre&gt;">
&lt;pre caption = "Output of uptime"&gt;
# &lt;i&gt;uptime&lt;/i&gt;
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
&lt;/pre&gt;
</pre>

</body>
</section>
<section>
<title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
<body>

<p>
The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
be used inside any child <c>&lt;body&gt;</c> tag, except for
<c>&lt;pre&gt;</c>.  
</p>

<p>
The <c>&lt;path&gt;</c> element is used to mark text that refers to an
<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a 
<e>simple filename</e>. This element is generally rendered with a monospaced 
font to offset it from the standard paragraph type.  
</p>

<p>
The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
input</e>.  Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
that they can type in that will perform some kind of action.  For example, all
the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
element because they represent something that the user could type in that is
not a path.  By using <c>&lt;c&gt;</c> elements, you'll help your readers
quickly identify commands that they need to type in.  Also, because
<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
necessary to surround user input with double-quotes</e>. For example, don't
refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence.  Avoiding
the use of unnecessary double-quotes makes a document more readable -- and 
adorable!
</p>

<p>
<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
I <e>really</e> should use semicolons more often.  As you can see, this text is
offset from the regular paragraph type for emphasis.  This helps to give your
prose more <e>punch</e>!
</p>

</body>
</section>
<section>
<title>&lt;mail&gt; and &lt;uri&gt;</title>
<body>

<p>
We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link 
some text with a particular email address, and takes the form <c>&lt;mail 
link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
</p>

<p>
The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
Internet.  It has two forms -- the first can be used when you want to have the
actual URI displayed in the body text, such as this link to
<uri>http://www.gentoo.org</uri>.  To create this link, I typed
<c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>.  The alternate form is
when you want to associate a URI with some other text -- for example, <uri
link="http://www.gentoo.org">the Gentoo Linux website</uri>.  To create 
<e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the 
Gentoo Linux website&lt;/uri&gt;</c>.
</p>

</body>
</section>
<section>
<title>Figures</title>

<body>

<p>
Here's how to insert a figure into a document -- <c>&lt;figure
link="mygfx.png" short="my picture" caption="my favorite picture of all
time"/&gt;</c>.  The <c>link=</c> attribute points to the actual graphic image,
the <c>short=</c> attribute specifies a short description (currently used for
the image's HTML <c>alt=</c> attribute), and a caption.  Not too difficult
:)  We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
for adding images without captions, borders, etc.
</p>

</body>
</section>
<section>
<title>Tables and lists</title>
<body>

<p>
Guide supports a simplified table syntax similar to that of HTML.  To start
a table, use a <c>&lt;table&gt;</c> tag.  Start a row with a <c>&lt;tr&gt;</c>
tag.  However, for inserting actual table data, we <e>don't</e> support the
HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
block.  You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the 
first row.  Currently, these tags don't support any attributes, but some will
be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
</p>

<p>
To create ordered or unordered lists, simply use the HTML-style
<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags.  List tags
should only appear inside a <c>&lt;body&gt;</c>, <c>&lt;ul&gt;</c> or
<c>&lt;ol&gt;</c> tag.  
</p>

</body>
</section>
<section>
<title>Intra-document references</title>
<body>

<p>
Guide makes it really easy to reference other parts of the document using
hyperlinks.  You can create a link pointing to <uri link="#doc_chap1">Chapter
One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
One&lt;/uri&gt;</c>.  To point to <uri link="#doc_chap1_sect2">section two of
Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
Chapter One&lt;/uri&gt;</c>.  To refer to figure 3 in chapter 1, type <c>&lt;uri
link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>.  Or, to refer to <uri 
link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri 
link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.  We'll be
adding other auto-link abilities (such as table support) soon.
</p>

<p>
However, some guides change often and using such "counting" can lead to broken
links. In order to cope with this, you can define a name for a
<c>&lt;chapter&gt;</c> or <c>&lt;section&gt;</c> by using the <c>id</c>
attribute, and then point to that attribute, like this:
</p>

<pre caption="Using the id attribute">
&lt;chapter id="foo"&gt;
&lt;title&gt;This is foo!&lt;/title&gt;
...
&lt;p&gt;
More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
&lt;/p&gt;
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Coding Style</title>
<section>
<title>Introduction</title>
<body>

<p>
Since all Gentoo Documentation is a joint effort and several people will
most likely change existing documentation, a coding style is needed.
A coding style contains two sections. The first one is regarding
internal coding - how the xml-tags are placed. The second one is
regarding the content - how not to confuse the reader.
</p>

<p>
Both sections are described next.
</p>

</body>
</section>
<section>
<title>Internal Coding Style</title>
<body>

<p>
<b>Newlines</b> must be placed immediately after <e>every</e>
GuideXML-tag (both opening as closing), except for:
<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>, 
<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
<c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
</p>

<p>
<b>Blank lines</b> must be placed immediately after <e>every</e>
<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>, 
<c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, 
<c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and 
<c>&lt;impo&gt;</c> (opening tags only).
</p>

<p>
<b>Word-wrapping</b> must be applied at 80 characters except inside
<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from 
this rule (for instance when a URL exceeds the maximum amount of characters). 
The editor must then wrap whenever the first whitespace occurs.
</p>

<p>
<b>Indentation</b> may not be used, except with the XML-constructs of which 
the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),  
<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation 
is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
tabs and <e>not</e> more spaces.
</p>

<p>
In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
<c>&lt;li&gt;</c> constructs, indentation must be used for the content.
</p>

<p>
An example for indentation is:
</p>

<pre caption = "Indentation Example">
&lt;table&gt;
&lt;tr&gt;
  &lt;th&gt;Foo&lt;/th&gt;
  &lt;th&gt;Bar&lt;/th&gt;
&lt;/tr&gt;
&lt;tr&gt;
  &lt;ti&gt;This is an example for indentation.&lt;/ti&gt;
  &lt;ti&gt;
    In case text cannot be shown within an 80-character wide line, you
    must use indentation if the parent tag allows it.
  &lt;/ti&gt;
&lt;/tr&gt;
&lt;/table&gt;

&lt;ul&gt;
  &lt;li&gt;First option&lt;/li&gt;
  &lt;li&gt;Second option&lt;/li&gt;
&lt;/ul&gt;
</pre>

<p>
<b>Attributes</b> may not have spaces in between the attribute, the
&quot;=&quot; mark, and the attribute value. As an example:
</p>

<pre caption="Attributes">
<comment>Wrong  :</comment>     &lt;pre caption = "Attributes"&gt;
<comment>Correct:</comment>     &lt;pre caption="Attributes"&gt;
</pre>

</body>
</section>
<section>
<title>External Coding Style</title>
<body>

<p>
Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and 
<c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple 
sentences are used. In that case, every sentence should end with a period (or 
other reading marks).
</p>

<p>
Every sentence, including those inside tables and listings, should start
with a capital letter.
</p>

<pre caption="Periods and capital letters">
&lt;ul&gt;
  &lt;li&gt;No period&lt;/li&gt;
  &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
&lt;/ul&gt;
</pre>

<p>
Code Listings should <e>always</e> have a <c>caption</c>.
</p>

<p>
Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
</p>

<p>
When you comment something inside a <c>&lt;pre&gt;</c> construct, only use
<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise,
use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e>
the subject of the comment.
</p>

<pre caption="Comment example">
<comment>(Substitute "john" with your user name)</comment>
# <i>id john</i>
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Handbook Format</title>
<section>
<title>Guide vs Book</title>
<body>

<p>
For high-volume documentation, such as the <uri
link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
broader format was needed. We designed a GuideXML-compatible enhancement that
allows us to write modular and multi-page documentation.
</p>

</body>
</section>
<section>
<title>Main File</title>
<body>

<p>
The first change is the need for a "master" document. This document contains no
real content, but links to the individual documentation modules. The syntaxis
doesn't differ much from GuideXML:
</p>

<pre caption="Example book usage">
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;

&lt;<i>book</i> link="example.xml"&gt;
&lt;title&gt;Example Book Usage&lt;/title&gt;

&lt;author...&gt;
  ...
&lt;/author&gt;

&lt;abstract&gt;
  ...
&lt;/abstract&gt;

&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
&lt;!-- See http://creativecommons.org/licenses/by-sa/1.0 --&gt;
&lt;license/&gt;

&lt;version&gt;...&lt;/version&gt;
&lt;date&gt;...&lt;/date&gt;
</pre>

<p>
So far no real differences (except for the <c>&lt;book&gt;</c> instead of
<c>&lt;guide&gt;</c> tag). Instead of starting with the individual
<c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the
equivalent of a separate part in a book:
</p>

<pre caption="Defining a part">
&lt;part&gt;
&lt;title&gt;Part One&lt;/title&gt;
&lt;abstract&gt;
  ...
&lt;/abstract&gt;

<comment>(Defining the several chapters)</comment>
&lt;/part&gt;
</pre>

<p>
Each part is accompanied by a <c>&lt;title&gt;</c> and an 
<c>&lt;abstract&gt;</c> which gives a small introduction to the part.
</p>

<p>
Inside each part, you define the individual <c>&lt;chapter&gt;</c>'s. Each
chapter <e>must</e> be a separate document. As a result it is no surprise that a
special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
document.
</p>

<pre caption="Defining a chapter">
&lt;chapter&gt;
&lt;title&gt;Chapter One&lt;/title&gt;
&lt;abstract&gt;
  This is a small explanation on chapter one.
&lt;/abstract&gt;

  &lt;include href="path/to/chapter-one.xml"/&gt;

&lt;/chapter&gt;
</pre>

</body>
</section>
<section>
<title>Designing the Individual Chapters</title>
<body>

<p>
The content of an individual chapter is structured as follows:
</p>

<pre caption="Chapter Syntax">
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;

&lt;!--  The content of this document is licensed under the CC-BY-SA license --&gt;
&lt;!--  See http://creativecommons.org/licenses/by-sa/1.0 --&gt;

&lt;sections&gt;

<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>

&lt;/sections&gt;
</pre>

<p>
Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
of <c>&lt;section&gt;</c> in a Guide).
</p>

</body>
</section>
</chapter>

<chapter>
<title>Resources</title>
<section>
<title>Start writing</title>
<body>

<p>
Guide has been specially designed to be "lean and mean" so that developers
can spend more time writing documentation and less time learning the actual XML
syntax.  Hopefully, this will allow developers who aren't unusually "doc-savvy"
to start writing quality Gentoo Linux documentation.  If you'd like to help (or 
have any questions about guide), please post a message to the <mail 
link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd 
like to tackle. Have fun!
</p>

</body>
</section>
</chapter>
</guide>
