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 Documentation Guide</title>
<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
<author title="Editor"><mail link="zhen@gentoo.org">John P. Davis</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>1.2</version>
<date>16 January 2002</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.  Two popular XSLT processors are <c>sabcmd</c>
(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c>
(found in the <path>dev-libs/libxslt</path> package).  From experience, we've
found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
processor.  </p>


<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're
ready to convert guide XML into web-ready HTML. In order to do this though,
it is necessary to get the latest snapshot of our website tree.
</p>

<p>The gzipped tarball for the website can be found
<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
</p>

<note>You can now download the full set of Gentoo Linux documentation for your language
of choice without having to download the full web tree. Please navigate to 
<uri>http://www.gentoo.org/dyn/doc-snapshots</uri> to find the tarballs.
</note>

<p>Now, extract the tarball.  Inside it, you'll find a <path>htdocs</path>
directory. Now, find <path>htdocs/doc/&lt;your lang&gt;/gentoo-x86-install.xml</path>
(The new user installation guide). This will be our source XML guide document.
The easiest way to perform the transformation is to change directories to the location of the
<path>guide.xsl</path> file.  Then, execute <c>xsltproc</c> as follows:
</p>

<pre caption="Transforming gentoo-x86-install.xml">
# <c>cd gentoo-web/xsl</c>
# <c>xsltproc guide.xsl ../doc/&lt;your lang&gt;/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-new.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>

<impo>If you are going to be submitting documents, it is necessary to read the 
<uri link="http://www.gentoo.org/doc/en/doc-developer-guide.xml">Gentoo Documentation Developer's Policy</uri>.
</impo>

<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.</p>

</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 <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail>
                and <mail link="gentoo-doc@gentoo.org">the gentoo-doc mailing list</mail>
                stating what you'd like to tackle.
                Have fun!</p>
        </body>
</section>
</chapter>
</guide>

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