/[gentoo]/xml/htdocs/doc/en/xml-guide.xml
Gentoo

Diff of /xml/htdocs/doc/en/xml-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.3 Revision 1.49
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.49 2005/08/23 09:18:12 neysx Exp $ -->
3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 4
6<guide link="/doc/en/xml-guide.xml"> 5<guide link="/doc/en/xml-guide.xml">
7<title>Gentoo Linux Documentation Guide</title> 6<title>Gentoo Linux XML Guide</title>
8<author title="Chief Architect"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
9 7
8<author title="Author">
9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10</author>
11<author title="Author"><!-- zhen@gentoo.org -->
12 John P. Davis
13</author>
14<author title="Editor">
15 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16</author>
17<author title="Editor">
18 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
19</author>
20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author>
23
24<abstract>
10<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide 25This guide shows you how to compose web documentation using the new lightweight
11XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
12itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. 27documentation, and this document itself was created using GuideXML. This guide
28assumes a basic working knowledge of XML and HTML.
13</abstract> 29</abstract>
14 30
31<!-- The content of this document is licensed under the CC-BY-SA license -->
32<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33<license/>
34
15<version>1.0</version> 35<version>2.25</version>
16<date>07 Mar 2002</date> 36<date>2005-08-23</date>
17 37
18<chapter> 38<chapter>
19<title>Guide basics</title> 39<title>Guide basics</title>
20
21<section> 40<section>
22<title>Guide XML design goals</title> 41<title>Guide XML design goals</title>
23<body> 42<body>
24 43
44<p>
25<p> The guide XML syntax is lightweight yet expressive, so that it is easy to 45The guide XML syntax is lightweight yet expressive, so that it is easy to
26learn yet also provides all the features we need for the creation of web 46learn yet also provides all the features we need for the creation of web
27documentation. The number of tags is kept to a minimum -- just those we need. 47documentation. The number of tags is kept to a minimum -- just those we need.
28This makes it easy to transform guide into other formats, such as DocBook 48This makes it easy to transform guide into other formats, such as DocBook
29XML/SGML or web-ready HTML. </p> 49XML/SGML or web-ready HTML.
50</p>
30 51
52<p>
31<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML 53The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
32documents.</p> 54documents.
55</p>
33 56
34</body> 57</body>
35</section>
36
37<section> 58</section>
38<title>How to transform guide XML into HTML</title> 59<section>
60<title>Further Resources</title>
39<body> 61<body>
40 62
41<p> Before we take a look at the guide syntax itself, it's helpful to know how
42guide XML is transformed into web-ready HTML. To do this, we use a special
43file called <path>guide-main.xsl</path>, along with a command-line XSLT processing
44tool (also called an "engine"). The <path>guide-main.xsl</path> file describes
45exactly how to transform the contents of the source guide XML document to
46create the target HTML file. Two popular XSLT processors are <c>sabcmd</c>
47(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c>
48(found in the <path>dev-libs/libxslt</path> package). From experience, we've
49found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
50processor. </p>
51
52<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're
53ready to convert guide XML into web-ready HTML. Here's how it works. First,
54download the latest snapshot of our Web site from
55<uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri
56link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri>
57file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path>
58directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find
59<path>gentoo-src/xml/install.xml</path>. (The new user installation guide).
60This will be our source XML guide document. The easiest way to perform the
61transformation is to change directories to the location of the
62<path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
63</p> 63<p>
64 64If you are planning on contributing documentation to Gentoo, or you want to
65<pre> 65test GuideXML, please read the <uri
66# <i>cd gentoo-web/xsl</i> 66link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which
67# <i>xsltproc guide-main.xsl ../xml/install.xml &gt; /tmp/install.html</i> 67contains tips and tricks for documentation development.
68</pre>
69
70<p> If all went well, you should have a web-ready version of
71<path>install.xml</path> at <path>/tmp/install.html</path>. For this document
72to display properly in a web browser, you may have to copy some files from
73<path>gentoo-web</path> to <path>/tmp</path>, such
74as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path>
75directory.
76</p> 68</p>
77 69
78</body> 70</body>
79</section> 71</section>
80</chapter> 72</chapter>
73
81<chapter> 74<chapter>
82 <title>Guide XML</title> 75<title>Guide XML</title>
83<section> 76<section>
84<title>Basic structure</title> 77<title>Basic structure</title>
85<body> 78<body>
86 79
87<p>Now that you know how to transform guide XML, you're ready to start learning 80<p>
88the guide XML syntax. We'll start with the the initial tags used in a guide 81Let's start learning the GuideXML syntax. We'll start with the the initial
89XML document: </p> 82tags used in a GuideXML document:
83</p>
90 84
91<pre caption="The initial part of a guide XML document"> 85<pre caption="The initial part of a guide XML document">
92&lt;?xml version='1.0'?&gt; 86&lt;?xml version="1.0" encoding="UTF-8"?&gt;
93&lt;guide&gt; 87&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
88&lt;!-- &#36;Header&#36; --&gt;
89
90&lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt;
94&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 91&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
95&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt; 92
96 <i>Daniel Robbins</i>&lt;/mail&gt; 93&lt;author title="<i>Author</i>"&gt;
94 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
97&lt;/author&gt; 95&lt;/author&gt;
98&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
99 <i>Thomas Flavel</i>&lt;/mail&gt;
100&lt;/author&gt;
101 96
97&lt;abstract&gt;
102&lt;abstract&gt;<i>This guide shows you how to compose web documentation using 98<i>This guide shows you how to compose web documentation using
103our new lightweight Gentoo guide XML syntax. This syntax is the official 99our new lightweight Gentoo GuideXML syntax. This syntax is the official
104format for Gentoo Linux web documentation, and this document itself was created 100format for Gentoo Linux web documentation, and this document itself was created
105using guide XML.</i> &lt;/abstract&gt; 101using GuideXML.</i>
102&lt;/abstract&gt;
103
104&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
105&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
106&lt;license/&gt;
106 107
107&lt;version&gt;<i>1.0</i>&lt;/version&gt; 108&lt;version&gt;<i>1.0</i>&lt;/version&gt;
108&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt; 109&lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
109</pre> 110</pre>
110 111
112<p>
111<p>On the first, line, we see the requisite tag that identifies this as an XML 113On the first lines, we see the requisite tag that identifies this as an XML
112document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire 114document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
115will be automatically modified by the CVS server and helps to track revisions.
116Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
113guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 117enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c>
118attribute is compulsory and should preferably contain the absolute path to the
119document relatively to the document root even though the file name alone will
120work. It is mainly used to generate a link to a printer-friendly version of
121your document. If you use a wrong value, the link to the printable version
122will either not work or point to a wrong document. The <c>lang</c> attribute
123can be used to specify the language code of your document. It is used to format
124the date and insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the
125specified language. The default is English.
126</p>
127
128<p>
114Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 129Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
115guide document. </p> 130guide document.
131</p>
116 132
133<p>
117<p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 134Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
118about the various authors of the document. Each <c>&lt;author&gt;</c> tag 135about the various authors of the document. Each <c>&lt;author&gt;</c> tag
119allows for an optional <c>title=</c> element, used to specify the author's 136allows for an optional <c>title=</c> element, used to specify the author's
120relationship to the document (author, co-author, editor, etc.). In this 137relationship to the document (author, co-author, editor, etc.). In this
121particular example, the authors' names are enclosed in another tag -- a 138particular example, the authors' names are enclosed in another tag -- a
122<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular 139<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
123person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no 140person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
124more than one <c>&lt;author&gt;</c> element is required per guide document. 141more than one <c>&lt;author&gt;</c> element is required per guide document.
125</p> 142</p>
126 143
144<p>
127<p>Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and 145Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
128<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the 146<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
129current version number, and the current version date (in DD MMM YYYY format) 147current version number, and the current version date (in YYYY-MM-DD format)
148respectively. Dates that are invalid or not in the YYYY-MM-DD format will
149appear verbatim in the rendered document.
150</p>
151
152<p>
130respectively. This rounds out the tags that should appear at the beginning of 153This rounds out the tags that should appear at the beginning of a guide
131a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> 154document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these
132tags, these tags shouldn't appear anywhere else except immediately inside the 155tags shouldn't appear anywhere else except immediately inside the
133<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 156<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
134required) that these tags appear before the content of the document. </p> 157required) that these tags appear before the content of the document.
158</p>
135 159
136</body> 160<p>
137</section> 161Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document
162under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
163Commons - Attribution / Share Alike</uri> license as required by the <uri
164link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
165</p>
138 166
167</body>
168</section>
139<section> 169<section>
140<title>Chapters and sections</title> 170<title>Chapters and sections</title>
141<body> 171<body>
172
173<p>
142<p>Once the initial tags have been specified, you're ready to start adding 174Once the initial tags have been specified, you're ready to start adding the
143the structural elements of the document. Guide documents are divided into 175structural elements of the document. Guide documents are divided into
144chapters, and each chapter can hold one or more sections. Every chapter 176chapters, and each chapter can hold one or more sections. Every chapter and
145and section has a title. Here's an example chapter with a single section, 177section has a title. Here's an example chapter with a single section,
146consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous 178consisting of a paragraph. If you append this XML to the XML in the <uri
179link="#doc_chap2_pre1">previous excerpt</uri> and append a
147excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid 180<c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid (if minimal)
148(if minimal) guide document: 181guide document:
149</p> 182</p>
150 183
151<pre> 184<pre caption="Minimal guide example">
152&lt;chapter&gt; 185&lt;chapter&gt;
153&lt;title&gt;<i>This is my chapter</i>&lt;/title&gt; 186&lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
154&lt;section&gt; 187&lt;section&gt;
155 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt; 188&lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
156 &lt;body&gt; 189&lt;body&gt;
190
191&lt;p&gt;
157 &lt;p&gt;<i>This is the actual text content of my section.</i>&lt;/p&gt; 192<i>This is the actual text content of my section.</i>
193&lt;/p&gt;
194
158 &lt;/body&gt; 195&lt;/body&gt;
159&lt;/section&gt; 196&lt;/section&gt;
160&lt;/chapter&gt; 197&lt;/chapter&gt;
161</pre> 198</pre>
162 199
200<p>
163<p>Above, I set the chapter title by adding a child <c>&lt;title&gt;</c> 201Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
164element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by 202element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
165adding a <c>&lt;section&gt;</c> element. If you look inside the 203adding a <c>&lt;section&gt;</c> element. If you look inside the
166<c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a 204<c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
167<c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c> 205<c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
168is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text 206is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
169content of this particular section. We'll look at the tags that are allowed 207content of this particular section. We'll look at the tags that are allowed
170inside a <c>&lt;body&gt;</c> element in a bit. </p> 208inside a <c>&lt;body&gt;</c> element in a bit.
209</p>
171 210
211<note>
172<note>A <c>&lt;guide&gt;</c> element can contain multiple 212A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
173<c>&lt;chapter&gt;</c> elements, and a <c>&lt;chapter&gt;</c> can contain 213elements, and a <c>&lt;chapter&gt;</c> can contain multiple
174multiple <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c> 214<c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
175element can only contain one <c>&lt;body&gt;</c> element. </note> 215element can only contain one <c>&lt;body&gt;</c> element.
216</note>
176 217
177</body> 218</body>
178</section> 219</section>
179
180<section> 220<section>
181<title>An example &lt;body&gt;</title> 221<title>An example &lt;body&gt;</title>
182<body> 222<body>
183<p> 223
184Now, 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:
185</p> 224<p>
186<pre> 225Now, it's time to learn how to mark up actual content. Here's the XML code for
226an example <c>&lt;body&gt;</c> element:
227</p>
228
229<pre caption="Example of a body element">
187&lt;p&gt; 230&lt;p&gt;
188This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file. 231This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
189&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website. 232&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
190Type &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. 233Type &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.
191&lt;/p&gt; 234&lt;/p&gt;
192 235
193&lt;pre&gt; 236&lt;pre caption="Code Sample"&gt;
194This is text output or code. 237This is text output or code.
195# &lt;i&gt;this is user input&lt;/i&gt; 238# &lt;i&gt;this is user input&lt;/i&gt;
196 239
197Make HTML/XML easier to read by using selective emphasis: 240Make HTML/XML easier to read by using selective emphasis:
198&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt; 241&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
199 242
200&lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt; 243&lt;comment&gt;(This is how to insert an inline note into the code block)&lt;/comment&gt;
201&lt;/pre&gt; 244&lt;/pre&gt;
202&lt;note&gt;This is a note.&lt;/note&gt; 245
203&lt;warn&gt;This is a warning.&lt;/warn&gt; 246&lt;note&gt;
204&lt;impo&gt;This is important.&lt;/impo&gt; 247This is a note.
248&lt;/note&gt;
249
250&lt;warn&gt;
251This is a warning.
252&lt;/warn&gt;
253
254&lt;impo&gt;
255This is important.
256&lt;/impo&gt;
205</pre> 257</pre>
258
259<p>
206<p>Now, here's how this <c>&lt;body&gt;</c> element is rendered:</p> 260Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
261</p>
207 262
208<p> 263<p>
209This is a paragraph. <path>/etc/passwd</path> is a file. 264This is a paragraph. <path>/etc/passwd</path> is a file.
210<uri>http://www.gentoo.org</uri> is my favorite website. 265<uri>http://forums.gentoo.org</uri> is my favorite web site.
211Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. 266Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
212</p> 267</p>
213 268
214<pre> 269<pre caption="Code Sample">
215This is text output or code. 270This is text output or code.
216# <i>this is user input</i> 271# <i>this is user input</i>
217 272
218Make HTML/XML easier to read by using selective emphasis: 273Make HTML/XML easier to read by using selective emphasis:
219&lt;foo&gt;<i>bar</i>&lt;/foo&gt; 274&lt;foo&gt;<i>bar</i>&lt;/foo&gt;
220 275
221<codenote>This is how to insert an inline note into the code block</codenote> 276<comment>(This is how to insert an inline note into the code block)</comment>
222</pre> 277</pre>
223<note>This is a note.</note>
224<warn>This is a warning.</warn>
225<impo>This is important.</impo>
226</body>
227</section>
228 278
279<note>
280This is a note.
281</note>
282
283<warn>
284This is a warning.
285</warn>
286
287<impo>
288This is important.
289</impo>
290
291</body>
292</section>
229<section> 293<section>
230<title>The &lt;body&gt; tags</title> 294<title>The &lt;body&gt; tags</title>
231<body> 295<body>
232 296
297<p>
233<p> We introduced a lot of new tags in the previous section -- here's what you 298We introduced a lot of new tags in the previous section -- here's what you
234need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code 299need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
235block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and 300block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
236<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text. 301<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
237Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit), 302Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
238these are the only tags that should appear immediately inside a 303these are the only tags that should appear immediately inside a
239<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be 304<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
240stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a 305stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
241<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 306<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
242preserves its whitespace exactly, making it well-suited for code excerpts.</p> 307preserves its whitespace exactly, making it well-suited for code excerpts.
308You can also name the <c>&lt;pre&gt;</c> tag:
309</p>
243 310
311<pre caption="Named &lt;pre&gt;">
312&lt;pre caption = "Output of uptime"&gt;
313# &lt;i&gt;uptime&lt;/i&gt;
31416:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
315&lt;/pre&gt;
316</pre>
317
244</body> 318</body>
245</section>
246<section> 319</section>
320<section>
247<title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title> 321<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title>
248<body> 322<body>
249 323
324<p>
250<p>The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can 325The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
251be used inside any child <c>&lt;body&gt;</c> tag, except for 326be used inside any child <c>&lt;body&gt;</c> tag, except for
327<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
252<c>&lt;pre&gt;</c>. </p> 328<c>&lt;pre&gt;</c>.
329</p>
253 330
331<p>
254<p>The <c>&lt;path&gt;</c> element is used to mark text that refers to an 332The <c>&lt;path&gt;</c> element is used to mark text that refers to an
255<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>. 333<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
256This element is generally rendered with a monospaced font to offset it from the 334<e>simple filename</e>. This element is generally rendered with a mono spaced
257standard paragraph type. </p> 335font to offset it from the standard paragraph type.
336</p>
258 337
338<p>
259<p>The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user 339The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
260input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something 340input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
261that they can type in that will perform some kind of action. For example, all 341that they can type in that will perform some kind of action. For example, all
262the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c> 342the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
263element because they represent something that the user could type in that is 343element because they represent something that the user could type in that is
264not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers 344not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
265quickly identify commands that they need to type in. Also, because 345quickly identify commands that they need to type in. Also, because
266<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely 346<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
267necessary to surround user input with double-quotes</e>. For example, don't 347necessary to surround user input with double-quotes</e>. For example, don't
268refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding 348refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
269the use of unnecessary double-quotes makes a document more readable -- and adorable!</p> 349the use of unnecessary double-quotes makes a document more readable -- and
350adorable!
351</p>
270 352
353<p>
354When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>,
355use <c>&lt;i&gt;</c> instead.
356</p>
357
358<p>
271<p><c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 359<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
272I <e>really</e> should use semicolons more often. As you can see, this text is 360I <e>really</e> should use semicolons more often. As you can see, this text is
273offset from the regular paragraph type for emphasis. This helps to give your 361offset from the regular paragraph type for emphasis. This helps to give your
274prose more <e>punch</e>!</p> 362prose more <e>punch</e>!
363</p>
275 364
276</body> 365</body>
277</section> 366</section>
278
279<section> 367<section>
280<title>&lt;mail&gt; and &lt;uri&gt;</title> 368<title>&lt;mail&gt; and &lt;uri&gt;</title>
281<body> 369<body>
282 370
371<p>
283<p>We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link some text 372We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
284with a particular email address, and takes the form <c>&lt;mail link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.</p> 373some text with a particular email address, and takes the form <c>&lt;mail
374link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
375</p>
285 376
377<p>
286<p>The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the 378The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
287Internet. It has two forms -- the first can be used when you want to have the 379It has two forms -- the first can be used when you want to have the actual URI
288actual URI displayed in the body text, such as this link to 380displayed in the body text, such as this link to
289<uri>http://www.gentoo.org</uri>. To create this link, I typed 381<uri>http://forums.gentoo.org</uri>. To create this link, I typed
290<c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is 382<c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
291when you want to associate a URI with some other text -- for example, <uri 383when you want to associate a URI with some other text -- for example, <uri
292link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e> 384link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
293link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the Gentoo Linux website&lt;/uri&gt;</c>. 385link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
386Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
387to link to other parts of the Gentoo web site. For instance, a link to the <uri
388link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
389link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
390even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
391link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
294</p> 392</p>
295 393
296</body> 394</body>
297</section> 395</section>
298
299<section> 396<section>
300<title>Figures</title> 397<title>Figures</title>
301
302<body> 398<body>
303 399
400<p>
304<p>Here's how to insert a figure into a document -- <c>&lt;figure 401Here's how to insert a figure into a document -- <c>&lt;figure
305link="mygfx.png" short="my picture" caption="my favorite picture of all 402link="mygfx.png" short="my picture" caption="my favorite picture of all
306time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image, 403time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
307the <c>short=</c> attribute specifies a short description (currently used for 404the <c>short=</c> attribute specifies a short description (currently used for
308the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult 405the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
309:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag 406:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
310for adding images without captions, borders, etc.</p> 407for adding images without captions, borders, etc.
408</p>
311 409
312</body> 410</body>
313</section> 411</section>
314<section> 412<section>
315<title>Tables and lists</title> 413<title>Tables and lists</title>
316<body> 414<body>
317 415
416<p>
318<p>Guide supports a simplified table syntax similar to that of HTML. To start 417Guide supports a simplified table syntax similar to that of HTML. To start
319a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c> 418a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
320tag. However, for inserting actual table data, we <e>don't</e> support the 419tag. However, for inserting actual table data, we <e>don't</e> support the
321HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a 420HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
322header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational 421header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
323block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> -- 422block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
324there's no requirement that <c>&lt;th&gt;</c> elements appear only in the 423-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
325first row. Currently, these tags don't support any attributes, but some will 424first row. Currently, these tags don't support any attributes, but some might
326be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon. 425be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) later.
426</p>
427
327</p> 428<p>
328
329<p> To create ordered or unordered lists, simply use the HTML-style 429To create ordered or unordered lists, simply use the XHTML-style
330<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags 430<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
331should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>, 431should only appear inside a <c>&lt;body&gt;</c>, <c>&lt;ul&gt;</c> or
332<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag. </p> 432<c>&lt;ol&gt;</c> tag. You need to close the tags as well (which is a general
433XML requirement).
434</p>
333 435
334</body> 436</body>
335</section> 437</section>
336
337<section> 438<section>
338<title>Intra-document references</title> 439<title>Intra-document references</title>
339<body> 440<body>
340 441
442<p>
341<p>Guide makes it really easy to reference other parts of the document using 443Guide makes it really easy to reference other parts of the document using
342hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter 444hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
343One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter 445One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
344One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of 446One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
345Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of 447Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
346Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri 448Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
347link="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>, 449link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
450link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
348type <c>&lt;uri link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be 451link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
349adding other auto-link abilities (such as table support) soon.</p> 452adding other auto-link abilities (such as table support) soon.
453</p>
454
455<p>
456However, some guides change often and using such "counting" can lead to broken
457links. In order to cope with this, you can define a name for a
458<c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
459the <c>id</c> attribute, and then point to that attribute, like this:
460</p>
461
462<pre caption="Using the id attribute">
463&lt;chapter id="foo"&gt;
464&lt;title&gt;This is foo!&lt;/title&gt;
465...
466&lt;p&gt;
467More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
468&lt;/p&gt;
469</pre>
350 470
351</body> 471</body>
352</section> 472</section>
353</chapter> 473</chapter>
474
475<chapter>
476<title>Coding Style</title>
477<section>
478<title>Introduction</title>
479<body>
480
481<p>
482Since all Gentoo Documentation is a joint effort and several people will
483most likely change existing documentation, a coding style is needed.
484A coding style contains two sections. The first one is regarding
485internal coding - how the XML-tags are placed. The second one is
486regarding the content - how not to confuse the reader.
487</p>
488
489<p>
490Both sections are described next.
491</p>
492
493</body>
494</section>
495<section>
496<title>Internal Coding Style</title>
497<body>
498
499<p>
500<b>Newlines</b> must be placed immediately after <e>every</e>
501GuideXML-tag (both opening as closing), except for:
502<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
503<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
504<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
505<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
506<c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
507</p>
508
509<p>
510<b>Blank lines</b> must be placed immediately after <e>every</e>
511<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
512<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
513<c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
514<c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
515<c>&lt;impo&gt;</c> (opening tags only).
516</p>
517
518<p>
519<b>Word-wrapping</b> must be applied at 80 characters except inside
520<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
521this rule (for instance when a URL exceeds the maximum amount of characters).
522The editor must then wrap whenever the first whitespace occurs.
523</p>
524
525<p>
526<b>Indentation</b> may not be used, except with the XML-constructs of which
527the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
528<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation
529is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
530tabs and <e>not</e> more spaces.
531</p>
532
533<p>
534In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
535<c>&lt;li&gt;</c> constructs, indentation must be used for the content.
536</p>
537
538<p>
539An example for indentation is:
540</p>
541
542<pre caption="Indentation Example">
543&lt;table&gt;
544&lt;tr&gt;
545 &lt;th&gt;Foo&lt;/th&gt;
546 &lt;th&gt;Bar&lt;/th&gt;
547&lt;/tr&gt;
548&lt;tr&gt;
549 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
550 &lt;ti&gt;
551 In case text cannot be shown within an 80-character wide line, you
552 must use indentation if the parent tag allows it
553 &lt;/ti&gt;
554&lt;/tr&gt;
555&lt;/table&gt;
556
557&lt;ul&gt;
558 &lt;li&gt;First option&lt;/li&gt;
559 &lt;li&gt;Second option&lt;/li&gt;
560&lt;/ul&gt;
561</pre>
562
563<p>
564<b>Attributes</b> may not have spaces in between the attribute, the
565&quot;=&quot; mark, and the attribute value. As an example:
566</p>
567
568<pre caption="Attributes">
569<comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
570<comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
571</pre>
572
573</body>
574</section>
575<section>
576<title>External Coding Style</title>
577<body>
578
579<p>
580Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
581<c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
582sentences are used. In that case, every sentence should end with a period (or
583other reading marks).
584</p>
585
586<p>
587Every sentence, including those inside tables and listings, should start
588with a capital letter.
589</p>
590
591<pre caption="Periods and capital letters">
592&lt;ul&gt;
593 &lt;li&gt;No period&lt;/li&gt;
594 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
595&lt;/ul&gt;
596</pre>
597
598<p>
599Code Listings should <e>always</e> have a <c>caption</c>.
600</p>
601
602<p>
603Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
604possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
605Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
606</p>
607
608<p>
609When you comment something inside a <c>&lt;pre&gt;</c> construct, use
610<c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
611that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
612for C code, etc.) Also place the comment <e>before</e> the subject of the
613comment.
614</p>
615
616<pre caption="Comment example">
617<comment>(Substitute "john" with your user name)</comment>
618# <i>id john</i>
619</pre>
620
621</body>
622</section>
623</chapter>
624
625<chapter>
626<title>Handbook Format</title>
627<section>
628<title>Guide vs Book</title>
629<body>
630
631<p>
632For high-volume documentation, such as the <uri
633link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
634broader format was needed. We designed a GuideXML-compatible enhancement that
635allows us to write modular and multi-page documentation.
636</p>
637
638</body>
639</section>
640<section>
641<title>Main File</title>
642<body>
643
644<p>
645The first change is the need for a "master" document. This document contains no
646real content, but links to the individual documentation modules. The syntaxis
647doesn't differ much from GuideXML:
648</p>
649
650<pre caption="Example book usage">
651&lt;?xml version='1.0' encoding='UTF-8'?&gt;
652&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
653&lt;!-- &#36;Header&#36; --&gt;
654
655&lt;<i>book</i> link="example.xml"&gt;
656&lt;title&gt;Example Book Usage&lt;/title&gt;
657
658&lt;author...&gt;
659 ...
660&lt;/author&gt;
661
662&lt;abstract&gt;
663 ...
664&lt;/abstract&gt;
665
666&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
667&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
668&lt;license/&gt;
669
670&lt;version&gt;...&lt;/version&gt;
671&lt;date&gt;...&lt;/date&gt;
672</pre>
673
674<p>
675So far no real differences (except for the <c>&lt;book&gt;</c> instead of
676<c>&lt;guide&gt;</c> tag). Instead of starting with the individual
677<c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the
678equivalent of a separate part in a book:
679</p>
680
681<pre caption="Defining a part">
682&lt;part&gt;
683&lt;title&gt;Part One&lt;/title&gt;
684&lt;abstract&gt;
685 ...
686&lt;/abstract&gt;
687
688<comment>(Defining the several chapters)</comment>
689&lt;/part&gt;
690</pre>
691
692<p>
693Each part is accompanied by a <c>&lt;title&gt;</c> and an
694<c>&lt;abstract&gt;</c> which gives a small introduction to the part.
695</p>
696
697<p>
698Inside each part, you define the individual <c>&lt;chapter&gt;</c>'s. Each
699chapter <e>must</e> be a separate document. As a result it is no surprise that a
700special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
701document.
702</p>
703
704<pre caption="Defining a chapter">
705&lt;chapter&gt;
706&lt;title&gt;Chapter One&lt;/title&gt;
707&lt;abstract&gt;
708 This is a small explanation on chapter one.
709&lt;/abstract&gt;
710
711 &lt;include href="path/to/chapter-one.xml"/&gt;
712
713&lt;/chapter&gt;
714</pre>
715
716</body>
717</section>
718<section>
719<title>Designing the Individual Chapters</title>
720<body>
721
722<p>
723The content of an individual chapter is structured as follows:
724</p>
725
726<pre caption="Chapter Syntax">
727&lt;?xml version='1.0' encoding='UTF-8'?&gt;
728&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
729&lt;!-- &#36;Header&#36; --&gt;
730
731&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
732&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
733
734&lt;sections&gt;
735
736&lt;version&gt;...&lt;/version&gt;
737&lt;date&gt;...&lt;/date&gt;
738
739<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
740
741&lt;/sections&gt;
742</pre>
743
744<p>
745Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
746<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
747of <c>&lt;section&gt;</c> in a Guide).
748</p>
749
750<p>
751Each individual chapter should have its own date and version elements. The
752latest date of all chapters and master document will be displayed when a user
753browses through all parts of the book.
754</p>
755
756</body>
757</section>
758</chapter>
759
354<chapter> 760<chapter>
355<title>Resources</title> 761<title>Resources</title>
356<section> 762<section>
357 <title>Start writing</title> 763<title>Start writing</title>
358 <body> 764<body>
765
766<p>
359 <p>Guide has been specially designed to be "lean and mean" so that developers 767Guide has been specially designed to be "lean and mean" so that developers can
360 can spend more time writing documentation and less time learning the actual XML 768spend more time writing documentation and less time learning the actual XML
361 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 769syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
362 to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please 770to start writing quality Gentoo Linux documentation. You might be interested
363 post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail> 771in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation
364 stating what you'd like to tackle. 772Development Tips &amp; Tricks</uri>. If you'd like to help (or have any
365 Have fun!</p> 773questions about guide), please post a message to the <mail
774link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
775like to tackle. Have fun!
776</p>
777
366 </body> 778</body>
367</section> 779</section>
368</chapter> 780</chapter>
369</guide> 781</guide>
370

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.49

  ViewVC Help
Powered by ViewVC 1.1.20