doc/en/xml-guide.xml

<?xml version='1.0' encoding="UTF-8"?>
<!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"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>

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

<version>2.0</version>
<date>12 May 2003</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>How to transform guide XML into HTML</title>
<body>

<p> Before we take a look at the guide syntax itself, it's helpful to know how
guide XML is transformed into web-ready HTML.  To do this, we use a special
file called <path>guide.xsl</path>, along with a command-line XSLT processing
tool (also called an "engine").  The <path>guide.xsl</path> file describes
exactly how to transform the contents of the source guide XML document to
create the target HTML file. The processing tool that Gentoo Linux uses
is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. </p>


<pre caption="Installing libxslt">
# <c>emerge libxslt</c>
</pre>

<p>Now that we have the way, we need the means, so to speak. In other words,
we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
that are available for download: </p>

<p><b>The first type contains the entire up-to-date Gentoo Linux website</b>.
Included are our XSL templates, so if you are planning to transform any documentation,
you will need this tarball. The tarball can be found 
<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.</p>

<p><b>The second type contains daily snapshots our XML documentation source</b> in 
every language that we offer. Please note that it is impossible to transform
documentation with this tarball, so please download the web tarball if you want to fully
develop your own documentation. These tarballs are especially useful for translators.
These tarballs can be found <uri link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
</p>

<p>After the web tarball is downloaded and extracted, go
to the directory where the tarball was extracted, and enter the 
<path>htdocs</path> directory. Browse around and get comfortable with the 
layout, but note the <path>xsl</path> and <path>doc</path> directories.
As you might have guessed, the XSL stylesheets are in <path>xsl</path>,
and our documentation is in <path>doc</path>. For testing purposes, we
will be using the Gentoo Linux CD Installation Guide, located at
<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations
of the XSL and XML file are known, we can do some transforming with
<c>xsltproc</c>. </p>

<pre caption="Transforming gentoo-x86-install.xml">
# <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
</pre>

<p> If all went well, you should have a web-ready version of
<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>.  For this document
to display properly in a web browser, you may have to copy some files from
<path>htdocs</path> to <path>/tmp</path>, such
as <path>css/main.css</path> and (to be safe) the entire <path>images</path>
directory.
</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 guide XML 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;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 guide XML syntax.  This syntax is the official
format for Gentoo Linux web documentation, and this document itself was created
using guide XML.</i> &lt;/abstract&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>

</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_pre2">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;p&gt;</c>, <c>&lt;ti&gt;</c>,
<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&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>

</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>
1	zhen	1.3	<?xml version='1.0' encoding="UTF-8"?>
2	drobbins	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4	zhen	1.2	<guide link="/doc/en/xml-guide.xml">
5	zhen	1.9	<title>Gentoo Linux XML Guide</title>
6	zhen	1.6	<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
7	zhen	1.9	<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
8	peesh	1.11	<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>
9	drobbins	1.1
10			<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide
11			XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document
12			itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML.
13			</abstract>
14
15	zhen	1.9	<version>2.0</version>
16	swift	1.12	<date>12 May 2003</date>
17	drobbins	1.1
18			<chapter>
19			<title>Guide basics</title>
20
21			<section>
22			<title>Guide XML design goals</title>
23			<body>
24
25			<p> The guide XML syntax is lightweight yet expressive, so that it is easy to
26			learn yet also provides all the features we need for the creation of web
27			documentation. The number of tags is kept to a minimum -- just those we need.
28			This makes it easy to transform guide into other formats, such as DocBook
29			XML/SGML or web-ready HTML. </p>
30
31			<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
32			documents.</p>
33
34			</body>
35			</section>
36
37			<section>
38			<title>How to transform guide XML into HTML</title>
39			<body>
40
41			<p> Before we take a look at the guide syntax itself, it's helpful to know how
42			guide XML is transformed into web-ready HTML. To do this, we use a special
43	zhen	1.6	file called <path>guide.xsl</path>, along with a command-line XSLT processing
44			tool (also called an "engine"). The <path>guide.xsl</path> file describes
45	drobbins	1.1	exactly how to transform the contents of the source guide XML document to
46	zhen	1.9	create the target HTML file. The processing tool that Gentoo Linux uses
47			is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. </p>
48	drobbins	1.1
49	zhen	1.6
50	zhen	1.9	<pre caption="Installing libxslt">
51			# <c>emerge libxslt</c>
52			</pre>
53	zhen	1.6
54	zhen	1.9	<p>Now that we have the way, we need the means, so to speak. In other words,
55			we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
56			that are available for download: </p>
57
58			<p><b>The first type contains the entire up-to-date Gentoo Linux website</b>.
59			Included are our XSL templates, so if you are planning to transform any documentation,
60			you will need this tarball. The tarball can be found
61			<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.</p>
62
63			<p><b>The second type contains daily snapshots our XML documentation source</b> in
64			every language that we offer. Please note that it is impossible to transform
65			documentation with this tarball, so please download the web tarball if you want to fully
66			develop your own documentation. These tarballs are especially useful for translators.
67			These tarballs can be found <uri link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
68	drobbins	1.1	</p>
69
70	zhen	1.9	<p>After the web tarball is downloaded and extracted, go
71			to the directory where the tarball was extracted, and enter the
72			<path>htdocs</path> directory. Browse around and get comfortable with the
73			layout, but note the <path>xsl</path> and <path>doc</path> directories.
74			As you might have guessed, the XSL stylesheets are in <path>xsl</path>,
75			and our documentation is in <path>doc</path>. For testing purposes, we
76			will be using the Gentoo Linux CD Installation Guide, located at
77			<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations
78			of the XSL and XML file are known, we can do some transforming with
79			<c>xsltproc</c>. </p>
80	zhen	1.6
81			<pre caption="Transforming gentoo-x86-install.xml">
82	peesh	1.11	# <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml > /tmp/install.html</c>
83	drobbins	1.1	</pre>
84
85			<p> If all went well, you should have a web-ready version of
86	zhen	1.6	<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document
87	drobbins	1.1	to display properly in a web browser, you may have to copy some files from
88	zhen	1.6	<path>htdocs</path> to <path>/tmp</path>, such
89	zhen	1.9	as <path>css/main.css</path> and (to be safe) the entire <path>images</path>
90	drobbins	1.1	directory.
91			</p>
92
93			</body>
94			</section>
95			</chapter>
96			<chapter>
97			<title>Guide XML</title>
98			<section>
99			<title>Basic structure</title>
100			<body>
101
102			<p>Now that you know how to transform guide XML, you're ready to start learning
103			the guide XML syntax. We'll start with the the initial tags used in a guide
104			XML document: </p>
105
106			<pre caption="The initial part of a guide XML document">
107	zhen	1.6	<?xml version='1.0' encoding="UTF-8"?>
108			<guide link="relative_link_to_your_guide">
109	drobbins	1.1	<title><i>Gentoo Linux Documentation Guide</i></title>
110			<author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>">
111			<i>Daniel Robbins</i></mail>
112			</author>
113			<author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>">
114			<i>Thomas Flavel</i></mail>
115			</author>
116
117			<abstract><i>This guide shows you how to compose web documentation using
118			our new lightweight Gentoo guide XML syntax. This syntax is the official
119			format for Gentoo Linux web documentation, and this document itself was created
120			using guide XML.</i> </abstract>
121
122			<version><i>1.0</i></version>
123			<date><i>29 Mar 2001</i></date>
124			</pre>
125
126			<p>On the first, line, we see the requisite tag that identifies this as an XML
127			document. Following it, there's a <c><guide></c> tag -- the entire
128			guide document is enclosed within a <c><guide> </guide></c> pair.
129			Next, there's a <c><title></c> tag, used to set the title for the entire
130			guide document. </p>
131
132			<p>Then, we come to the <c><author></c> tags, which contain information
133			about the various authors of the document. Each <c><author></c> tag
134			allows for an optional <c>title=</c> element, used to specify the author's
135			relationship to the document (author, co-author, editor, etc.). In this
136			particular example, the authors' names are enclosed in another tag -- a
137			<c><mail></c> tag, used to specify an email address for this particular
138			person. The <c><mail></c> tag is optional and can be omitted, and no
139			more than one <c><author></c> element is required per guide document.
140			</p>
141
142			<p>Next, we come to the <c><abstract></c>, <c><version></c> and
143			<c><date></c> tags, used to specify a summary of the document, the
144			current version number, and the current version date (in DD MMM YYYY format)
145			respectively. This rounds out the tags that should appear at the beginning of
146			a guide document. Besides the <c><title></c> and <c><mail></c>
147			tags, these tags shouldn't appear anywhere else except immediately inside the
148			<c><guide></c> tag, and for consistency it's recommended (but not
149			required) that these tags appear before the content of the document. </p>
150
151			</body>
152			</section>
153
154			<section>
155			<title>Chapters and sections</title>
156			<body>
157			<p>Once the initial tags have been specified, you're ready to start adding
158			the structural elements of the document. Guide documents are divided into
159			chapters, and each chapter can hold one or more sections. Every chapter
160			and section has a title. Here's an example chapter with a single section,
161			consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous
162			excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid
163			(if minimal) guide document:
164			</p>
165
166			<pre>
167			<chapter>
168			<title><i>This is my chapter</i></title>
169			<section>
170			<title><i>This is section one of my chapter</i></title>
171			<body>
172			<p><i>This is the actual text content of my section.</i></p>
173			</body>
174			</section>
175			</chapter>
176			</pre>
177
178			<p>Above, I set the chapter title by adding a child <c><title></c>
179			element to the <c><chapter></c> element. Then, I created a section by
180			adding a <c><section></c> element. If you look inside the
181			<c><section></c> element, you'll see that it has two child elements -- a
182			<c><title></c> and a <c><body></c>. While the <c><title></c>
183			is nothing new, the <c><body></c> is -- it contains the actual text
184			content of this particular section. We'll look at the tags that are allowed
185			inside a <c><body></c> element in a bit. </p>
186
187			<note>A <c><guide></c> element can contain multiple
188			<c><chapter></c> elements, and a <c><chapter></c> can contain
189			multiple <c><section></c> elements. However, a <c><section></c>
190			element can only contain one <c><body></c> element. </note>
191
192			</body>
193			</section>
194
195			<section>
196			<title>An example <body></title>
197			<body>
198			<p>
199			Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element:
200			</p>
201			<pre>
202			<p>
203			This is a paragraph. <path>/etc/passwd</path> is a file.
204			<uri>http://www.gentoo.org</uri> is my favorite website.
205			Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
206			</p>
207
208			<pre>
209			This is text output or code.
210			# <i>this is user input</i>
211
212			Make HTML/XML easier to read by using selective emphasis:
213			<foo><i>bar</i></foo>
214
215			<codenote>This is how to insert an inline note into the code block</codenote>
216			</pre>
217			<note>This is a note.</note>
218			<warn>This is a warning.</warn>
219			<impo>This is important.</impo>
220			</pre>
221			<p>Now, here's how this <c><body></c> element is rendered:</p>
222
223			<p>
224			This is a paragraph. <path>/etc/passwd</path> is a file.
225			<uri>http://www.gentoo.org</uri> is my favorite website.
226			Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
227			</p>
228
229			<pre>
230			This is text output or code.
231			# <i>this is user input</i>
232
233			Make HTML/XML easier to read by using selective emphasis:
234			<foo><i>bar</i></foo>
235
236			<codenote>This is how to insert an inline note into the code block</codenote>
237			</pre>
238			<note>This is a note.</note>
239			<warn>This is a warning.</warn>
240			<impo>This is important.</impo>
241			</body>
242			</section>
243
244			<section>
245			<title>The <body> tags</title>
246			<body>
247
248			<p> We introduced a lot of new tags in the previous section -- here's what you
249			need to know. The <c><p></c> (paragraph), <c><pre></c> (code
250			block), <c><note></c>, <c><warn></c> (warning) and
251			<c><impo></c> (important) tags all can contain one or more lines of text.
252			Besides the <c><table></c> element (which we'll cover in just a bit),
253			these are the only tags that should appear immediately inside a
254			<c><body></c> element. Another thing -- these tags <e>should not</e> be
255			stacked -- in other words, don't put a <c><note></c> element inside a
256			<c><p></c> element. As you might guess, the <c><pre></c> element
257	swift	1.12	preserves its whitespace exactly, making it well-suited for code excerpts.
258			You can also name the <c><pre></c> tag:</p>
259
260			<pre caption = "Named <pre>">
261			<pre caption = "Output of uptime">
262			# <i>uptime</i>
263			16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
264			</pre>
265			</pre>
266	drobbins	1.1
267			</body>
268			</section>
269			<section>
270			<title><path>, <c> and <e></title>
271			<body>
272
273			<p>The <c><path></c>, <c><c></c> and <c><e></c> elements can
274			be used inside any child <c><body></c> tag, except for
275			<c><pre></c>. </p>
276
277			<p>The <c><path></c> element is used to mark text that refers to an
278			<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>.
279			This element is generally rendered with a monospaced font to offset it from the
280			standard paragraph type. </p>
281
282			<p>The <c><c></c> element is used to mark up a <e>command</e> or <e>user
283			input</e>. Think of <c><c></c> as a way to alert the reader to something
284			that they can type in that will perform some kind of action. For example, all
285			the XML tags displayed in this document are enclosed in a <c><c></c>
286			element because they represent something that the user could type in that is
287			not a path. By using <c><c></c> elements, you'll help your readers
288			quickly identify commands that they need to type in. Also, because
289			<c><c></c> elements are already offset from regular text, <e>it is rarely
290			necessary to surround user input with double-quotes</e>. For example, don't
291			refer to a "<c><c></c>" element like I did in this sentence. Avoiding
292			the use of unnecessary double-quotes makes a document more readable -- and adorable!</p>
293
294			<p><c><e></c> is used to apply emphasis to a word or phrase; for example:
295			I <e>really</e> should use semicolons more often. As you can see, this text is
296			offset from the regular paragraph type for emphasis. This helps to give your
297			prose more <e>punch</e>!</p>
298
299			</body>
300			</section>
301
302			<section>
303			<title><mail> and <uri></title>
304			<body>
305
306			<p>We've taken a look at the <c><mail></c> tag earlier; it's used to link some text
307			with a particular email address, and takes the form <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.</p>
308
309			<p>The <c><uri></c> tag is used to point to files/locations on the
310			Internet. It has two forms -- the first can be used when you want to have the
311			actual URI displayed in the body text, such as this link to
312			<uri>http://www.gentoo.org</uri>. To create this link, I typed
313			<c><uri>http://www.gentoo.org</uri></c>. The alternate form is
314			when you want to associate a URI with some other text -- for example, <uri
315			link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e>
316			link, I typed <c><uri link="http://www.gentoo.org">the Gentoo Linux website</uri></c>.
317			</p>
318
319			</body>
320			</section>
321
322			<section>
323			<title>Figures</title>
324
325			<body>
326
327			<p>Here's how to insert a figure into a document -- <c><figure
328			link="mygfx.png" short="my picture" caption="my favorite picture of all
329			time"/></c>. The <c>link=</c> attribute points to the actual graphic image,
330			the <c>short=</c> attribute specifies a short description (currently used for
331			the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
332			:) We also support the standard HTML-style <img src="foo.gif"/> tag
333			for adding images without captions, borders, etc.</p>
334
335			</body>
336			</section>
337			<section>
338			<title>Tables and lists</title>
339			<body>
340
341			<p>Guide supports a simplified table syntax similar to that of HTML. To start
342			a table, use a <c><table></c> tag. Start a row with a <c><tr></c>
343			tag. However, for inserting actual table data, we <e>don't</e> support the
344			HTML <td> tag; instead, use the <c><th></c> if you are inserting a
345			header, and <c><ti></c> if you are inserting a normal informational
346			block. You can use a <c><th></c> anywhere you can use a <c><ti></c> --
347			there's no requirement that <c><th></c> elements appear only in the
348			first row. Currently, these tags don't support any attributes, but some will
349			be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.
350			</p>
351
352			<p> To create ordered or unordered lists, simply use the HTML-style
353			<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags
354			should only appear inside a <c><p></c>, <c><ti></c>,
355			<c><note></c>, <c><warn></c> or <c><impo></c> tag. </p>
356
357			</body>
358			</section>
359
360			<section>
361			<title>Intra-document references</title>
362			<body>
363
364			<p>Guide makes it really easy to reference other parts of the document using
365			hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
366			One</uri> by typing <c><uri link="#doc_chap1">Chapter
367			One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
368			Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
369			Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri
370			link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>,
371			type <c><uri link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be
372			adding other auto-link abilities (such as table support) soon.</p>
373
374			</body>
375			</section>
376			</chapter>
377			<chapter>
378			<title>Resources</title>
379			<section>
380			<title>Start writing</title>
381			<body>
382			<p>Guide has been specially designed to be "lean and mean" so that developers
383			can spend more time writing documentation and less time learning the actual XML
384			syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
385			to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please
386	zhen	1.10	post a message to the <mail link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail>
387	drobbins	1.1	stating what you'd like to tackle.
388			Have fun!</p>
389			</body>
390			</section>
391			</chapter>
392			</guide>