/[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.16 Revision 1.17
10<author title="Author"> 10<author title="Author">
11 <mail link="zhen@gentoo.org">John P. Davis</mail> 11 <mail link="zhen@gentoo.org">John P. Davis</mail>
12</author> 12</author>
13<author title="Editor"> 13<author title="Editor">
14 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 14 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
15</author> 15</author>
16 16
17<license/> 17<license/>
18<abstract> 18<abstract>
19This guide shows you how to compose web documentation using the new lightweight 19This guide shows you how to compose web documentation using the new lightweight
20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21documentation, and this document itself was created using GuideXML. This guide 21documentation, and this document itself was created using GuideXML. This guide
22assumes a basic working knowledge of XML and HTML. 22assumes a basic working knowledge of XML and HTML.
23</abstract> 23</abstract>
24 24
25<version>2.0</version> 25<version>2.1</version>
26<date>October 9, 2003</date> 26<date>October 14, 2003</date>
27 27
28<chapter> 28<chapter>
29<title>Guide basics</title> 29<title>Guide basics</title>
30
31<section> 30<section>
32<title>Guide XML design goals</title> 31<title>Guide XML design goals</title>
33<body> 32<body>
34 33
35<p> 34<p>
36The guide XML syntax is lightweight yet expressive, so that it is easy to 35The guide XML syntax is lightweight yet expressive, so that it is easy to
37learn yet also provides all the features we need for the creation of web 36learn yet also provides all the features we need for the creation of web
38documentation. The number of tags is kept to a minimum -- just those we need. 37documentation. The number of tags is kept to a minimum -- just those we need.
39This makes it easy to transform guide into other formats, such as DocBook 38This makes it easy to transform guide into other formats, such as DocBook
40XML/SGML or web-ready HTML. 39XML/SGML or web-ready HTML.
41</p> 40</p>
42 41
43<p> 42<p>
44The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML 43The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45documents. 44documents.
46</p> 45</p>
47 46
48</body> 47</body>
49</section> 48</section>
50
51<section> 49<section>
52<title>How to transform guide XML into HTML</title> 50<title>How to transform guide XML into HTML</title>
53<body> 51<body>
54 52
55<p> 53<p>
56Before we take a look at the guide syntax itself, it's helpful to know how 54Before we take a look at the guide syntax itself, it's helpful to know how
57guide XML is transformed into web-ready HTML. To do this, we use a special 55guide XML is transformed into web-ready HTML. To do this, we use a special
58file called <path>guide.xsl</path>, along with a command-line XSLT processing 56file called <path>guide.xsl</path>, along with a command-line XSLT processing
59tool (also called an "engine"). The <path>guide.xsl</path> file describes 57tool (also called an "engine"). The <path>guide.xsl</path> file describes
60exactly how to transform the contents of the source guide XML document to 58exactly how to transform the contents of the source guide XML document to
61create the target HTML file. The processing tool that Gentoo Linux uses 59create the target HTML file. The processing tool that Gentoo Linux uses
62is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. 60is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
63</p> 61</p>
64 62
65<pre caption="Installing libxslt"> 63<pre caption="Installing libxslt">
66# <c>emerge libxslt</c> 64# <i>emerge libxslt</i>
67</pre> 65</pre>
68 66
69<p> 67<p>
70Now that we have the way, we need the means, so to speak. In other words, 68Now that we have the way, we need the means, so to speak. In other words,
71we need some Gentoo XML documents to transform. Gentoo has two types of tarballs 69we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
72that are available for download: 70that are available for download:
73</p> 71</p>
74 72
75<p> 73<p>
76<b>The first type contains the entire up-to-date Gentoo Linux website</b>. 74<b>The first type contains the entire up-to-date Gentoo Linux website</b>.
77Included are our XSL templates, so if you are planning to transform any 75Included are our XSL templates, so if you are planning to transform any
78documentation, you will need this tarball. The tarball can be found <uri 76documentation, you will need this tarball. The tarball can be found <uri
79link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>. 77link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
80</p> 78</p>
81 79
88link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>. 86link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
89</p> 87</p>
90 88
91<p> 89<p>
92After the web tarball is downloaded and extracted, go to the directory where 90After the web tarball is downloaded and extracted, go to the directory where
93the tarball was extracted, and enter the <path>htdocs</path> directory. Browse 91the tarball was extracted, and enter the <path>htdocs</path> directory. Browse
94around and get comfortable with the layout, but note the <path>xsl</path> and 92around and get comfortable with the layout, but note the <path>xsl</path> and
95<path>doc</path> directories. As you might have guessed, the XSL stylesheets are 93<path>doc</path> directories. As you might have guessed, the XSL stylesheets are
96in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing 94in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing
97purposes, we will be using the Gentoo Linux CD Installation Guide, located at 95purposes, we will be using the Gentoo Linux CD Installation Guide, located at
98<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL 96<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL
99and XML file are known, we can do some transforming with <c>xsltproc</c>. 97and XML file are known, we can do some transforming with <c>xsltproc</c>.
100</p> 98</p>
101 99
102<pre caption="Transforming gentoo-x86-install.xml"> 100<pre caption="Transforming gentoo-x86-install.xml">
103# <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c> 101# <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</i>
104</pre> 102</pre>
105 103
106<p> 104<p>
107If all went well, you should have a web-ready version of 105If all went well, you should have a web-ready version of
108<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For 106<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For
109this document to display properly in a web browser, you may have to copy some 107this document to display properly in a web browser, you may have to copy some
110files from <path>htdocs</path> to <path>/tmp</path>, such as 108files from <path>htdocs</path> to <path>/tmp</path>, such as
111<path>css/main.css</path> and (to be safe) the entire <path>images</path> 109<path>css/main.css</path> and (to be safe) the entire <path>images</path>
112directory. 110directory.
113</p> 111</p>
114 112
115</body> 113</body>
116</section> 114</section>
117</chapter> 115</chapter>
118 116
179a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> 177a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
180tags, these tags shouldn't appear anywhere else except immediately inside the 178tags, these tags shouldn't appear anywhere else except immediately inside the
181<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 179<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
182required) that these tags appear before the content of the document. 180required) that these tags appear before the content of the document.
183</p> 181</p>
184 182
185<p> 183<p>
186Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the 184Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
187document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative 185document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
188Commons - Attribution / Share Alike</uri> license as required by the <uri 186Commons - Attribution / Share Alike</uri> license as required by the <uri
189link="/doc/en/doc-policy.xml">Documentation Policy</uri>. 187link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
190</p> 188</p>
191 189
192</body> 190</body>
193</section> 191</section>
194
195<section> 192<section>
196<title>Chapters and sections</title> 193<title>Chapters and sections</title>
197<body> 194<body>
198 195
199<p> 196<p>
200Once the initial tags have been specified, you're ready to start adding 197Once the initial tags have been specified, you're ready to start adding
201the structural elements of the document. Guide documents are divided into 198the structural elements of the document. Guide documents are divided into
202chapters, and each chapter can hold one or more sections. Every chapter 199chapters, and each chapter can hold one or more sections. Every chapter
203and section has a title. Here's an example chapter with a single section, 200and section has a title. Here's an example chapter with a single section,
204consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous 201consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
205excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid 202excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
206(if minimal) guide document: 203(if minimal) guide document:
207</p> 204</p>
208 205
209<pre> 206<pre>
230<c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c> 227<c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
231is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text 228is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
232content of this particular section. We'll look at the tags that are allowed 229content of this particular section. We'll look at the tags that are allowed
233inside a <c>&lt;body&gt;</c> element in a bit. 230inside a <c>&lt;body&gt;</c> element in a bit.
234</p> 231</p>
235 232
236<note> 233<note>
237A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c> 234A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
238elements, and a <c>&lt;chapter&gt;</c> can contain multiple 235elements, and a <c>&lt;chapter&gt;</c> can contain multiple
239<c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c> 236<c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
240element can only contain one <c>&lt;body&gt;</c> element. 237element can only contain one <c>&lt;body&gt;</c> element.
241</note> 238</note>
242 239
243</body> 240</body>
244</section> 241</section>
245
246<section> 242<section>
247<title>An example &lt;body&gt;</title> 243<title>An example &lt;body&gt;</title>
248<body> 244<body>
249 245
250<p> 246<p>
251Now, 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: 247Now, 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:
252</p> 248</p>
253 249
254<pre> 250<pre>
255&lt;p&gt; 251&lt;p&gt;
256This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file. 252This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
257&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website. 253&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
258Type &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. 254Type &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.
259&lt;/p&gt; 255&lt;/p&gt;
260 256
303 299
304<note> 300<note>
305This is a note. 301This is a note.
306</note> 302</note>
307 303
308<warn> 304<warn>
309This is a warning. 305This is a warning.
310</warn> 306</warn>
311 307
312<impo> 308<impo>
313This is important. 309This is important.
314</impo> 310</impo>
315 311
316</body> 312</body>
317</section> 313</section>
318
319<section> 314<section>
320<title>The &lt;body&gt; tags</title> 315<title>The &lt;body&gt; tags</title>
321<body> 316<body>
322 317
323<p> 318<p>
324We introduced a lot of new tags in the previous section -- here's what you 319We introduced a lot of new tags in the previous section -- here's what you
325need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code 320need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
326block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and 321block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
327<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text. 322<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
328Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit), 323Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
329these are the only tags that should appear immediately inside a 324these are the only tags that should appear immediately inside a
330<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be 325<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
331stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a 326stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
332<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 327<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
333preserves its whitespace exactly, making it well-suited for code excerpts. 328preserves its whitespace exactly, making it well-suited for code excerpts.
372necessary to surround user input with double-quotes</e>. For example, don't 367necessary to surround user input with double-quotes</e>. For example, don't
373refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding 368refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
374the use of unnecessary double-quotes makes a document more readable -- and 369the use of unnecessary double-quotes makes a document more readable -- and
375adorable! 370adorable!
376</p> 371</p>
377 372
378<p> 373<p>
379<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 374<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
380I <e>really</e> should use semicolons more often. As you can see, this text is 375I <e>really</e> should use semicolons more often. As you can see, this text is
381offset from the regular paragraph type for emphasis. This helps to give your 376offset from the regular paragraph type for emphasis. This helps to give your
382prose more <e>punch</e>! 377prose more <e>punch</e>!
383</p> 378</p>
384 379
385</body> 380</body>
386</section> 381</section>
387
388<section> 382<section>
389<title>&lt;mail&gt; and &lt;uri&gt;</title> 383<title>&lt;mail&gt; and &lt;uri&gt;</title>
390<body> 384<body>
391 385
392<p> 386<p>
393We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link 387We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
394some text with a particular email address, and takes the form <c>&lt;mail 388some text with a particular email address, and takes the form <c>&lt;mail
395link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. 389link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
396</p> 390</p>
397 391
398<p> 392<p>
399The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the 393The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
400Internet. It has two forms -- the first can be used when you want to have the 394Internet. It has two forms -- the first can be used when you want to have the
401actual URI displayed in the body text, such as this link to 395actual URI displayed in the body text, such as this link to
402<uri>http://www.gentoo.org</uri>. To create this link, I typed 396<uri>http://www.gentoo.org</uri>. To create this link, I typed
403<c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is 397<c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
404when you want to associate a URI with some other text -- for example, <uri 398when you want to associate a URI with some other text -- for example, <uri
405link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create 399link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
406<e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the 400<e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the
407Gentoo Linux website&lt;/uri&gt;</c>. 401Gentoo Linux website&lt;/uri&gt;</c>.
408</p> 402</p>
409 403
410</body> 404</body>
411</section> 405</section>
412
413<section> 406<section>
414<title>Figures</title> 407<title>Figures</title>
415 408
416<body> 409<body>
417 410
418<p> 411<p>
419Here's how to insert a figure into a document -- <c>&lt;figure 412Here's how to insert a figure into a document -- <c>&lt;figure
420link="mygfx.png" short="my picture" caption="my favorite picture of all 413link="mygfx.png" short="my picture" caption="my favorite picture of all
421time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image, 414time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
422the <c>short=</c> attribute specifies a short description (currently used for 415the <c>short=</c> attribute specifies a short description (currently used for
423the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult 416the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
424:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag 417:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
425for adding images without captions, borders, etc. 418for adding images without captions, borders, etc.
426</p> 419</p>
427 420
440block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> 433block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
441-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the 434-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
442first row. Currently, these tags don't support any attributes, but some will 435first row. Currently, these tags don't support any attributes, but some will
443be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon. 436be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
444</p> 437</p>
445 438
446<p> 439<p>
447To create ordered or unordered lists, simply use the HTML-style 440To create ordered or unordered lists, simply use the HTML-style
448<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags 441<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
449should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>, 442should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
450<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag. 443<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
451</p> 444</p>
452 445
453</body> 446</body>
454</section> 447</section>
455
456<section> 448<section>
457<title>Intra-document references</title> 449<title>Intra-document references</title>
458<body> 450<body>
459 451
460<p> 452<p>
461Guide makes it really easy to reference other parts of the document using 453Guide makes it really easy to reference other parts of the document using
462hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter 454hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
463One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter 455One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
464One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of 456One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
465Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of 457Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
466Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri 458Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
467link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri 459link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
468link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri 460link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
469link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be 461link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
470adding other auto-link abilities (such as table support) soon. 462adding other auto-link abilities (such as table support) soon.
471</p> 463</p>
472 464
473</body> 465</body>
474</section> 466</section>
475</chapter> 467</chapter>
476 468
477<chapter> 469<chapter>
470<title>Coding Style</title>
471<section>
472<title>Introduction</title>
473<body>
474
475<p>
476Since all Gentoo Documentation is a joint effort and several people will
477most likely change existing documentation, a coding style is needed.
478A coding style contains two sections. The first one is regarding
479internal coding - how the xml-tags are placed. The second one is
480regarding the content - how not to confuse the reader.
481</p>
482
483<p>
484Both sections are described next.
485</p>
486
487</body>
488</section>
489<section>
490<title>Internal Coding Style</title>
491<body>
492
493<p>
494<b>Newlines</b> must be placed immediately after <e>every</e>
495GuideXML-tag (both opening as closing), except for:
496<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
497<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
498<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
499<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
500<c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
501</p>
502
503<p>
504<b>Blank lines</b> must be placed immediately after <e>every</e>
505<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
506<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
507<c>&lt;author&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>,
508<c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and <c>&lt;impo&gt;</c> (opening tags
509only).
510</p>
511
512<p>
513<b>Word-wrapping</b> must be applied at 80 characters except inside
514<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
515this rule (for instance when a URL exceeds the maximum amount of characters).
516The editor must then wrap whenever the first whitespace occurs.
517</p>
518
519<p>
520<b>Indentation</b> may not be used, except with the XML-constructs of which
521the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
522<c>&lt;ul&gt;</c> and <c>&lt;ol&gt;</c>. If indentation is used, it
523<e>must</e> be two spaces for each indentation. That means <e>no</e> tabs and
524<e>not</e> more spaces.
525</p>
526
527<p>
528In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
529<c>&lt;li&gt;</c> constructs, indentation must be used for the content.
530</p>
531
532<p>
533An example for indentation is:
534</p>
535
536<pre caption = "Indentation Example">
537&lt;table&gt;
538&lt;tr&gt;
539 &lt;th&gt;Foo&lt;/th&gt;
540 &lt;th&gt;Bar&lt;/th&gt;
541&lt;/tr&gt;
542&lt;tr&gt;
543 &lt;ti&gt;This is an example for indentation.&lt;/ti&gt;
544 &lt;ti&gt;
545 In case text cannot be shown within an 80-character wide line, you
546 must use indentation if the parent tag allows it.
547 &lt;/ti&gt;
548&lt;/tr&gt;
549&lt;/table&gt;
550
551&lt;ul&gt;
552 &lt;li&gt;First option&lt;/li&gt;
553 &lt;li&gt;Second option&lt;/li&gt;
554&lt;/ul&gt;
555</pre>
556
557<p>
558<b>Attributes</b> may not have spaces in between the attribute, the
559&quot;=&quot; mark, and the attribute value. As an example:
560</p>
561
562<pre caption="Attributes">
563<comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
564<comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
565</pre>
566
567</body>
568</section>
569<section>
570<title>External Coding Style</title>
571<body>
572
573<p>
574Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
575<c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
576sentences are used. In that case, every sentence should end with a period (or
577other reading marks).
578</p>
579
580<p>
581Every sentence, including those inside tables and listings, should start
582with a capital letter.
583</p>
584
585<pre caption="Periods and capital letters">
586&lt;ul&gt;
587 &lt;li&gt;No period&lt;/li&gt;
588 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
589&lt;/ul&gt;
590</pre>
591
592<p>
593Code Listings should <e>always</e> have a <c>caption</c>.
594</p>
595
596<p>
597Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
598possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
599Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
600</p>
601
602</body>
603</section>
604</chapter>
605
606<chapter>
478<title>Resources</title> 607<title>Resources</title>
479<section> 608<section>
480<title>Start writing</title> 609<title>Start writing</title>
481<body> 610<body>
482 611
483<p> 612<p>
484Guide has been specially designed to be "lean and mean" so that developers 613Guide has been specially designed to be "lean and mean" so that developers
485can spend more time writing documentation and less time learning the actual XML 614can spend more time writing documentation and less time learning the actual XML
486syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 615syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
487to start writing quality Gentoo Linux documentation. If you'd like to help (or 616to start writing quality Gentoo Linux documentation. If you'd like to help (or
488have any questions about guide), please post a message to the <mail 617have any questions about guide), please post a message to the <mail
489link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd 618link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
490like to tackle. Have fun! 619like to tackle. Have fun!
491</p> 620</p>
492 621

Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17

  ViewVC Help
Powered by ViewVC 1.1.20