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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.69 - (hide annotations) (download) (as text)
Sat Feb 28 01:34:20 2009 UTC (5 years, 7 months ago) by nightmorph
Branch: MAIN
Changes since 1.68: +8 -5 lines
File MIME type: application/xml
econf doesn't need explicit die, bug 253629

1 cam 1.41 <?xml version="1.0" encoding="UTF-8"?>
2 nightmorph 1.69 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.68 2008/03/09 13:13:15 neysx Exp $ -->
3 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 neysx 1.67 <guide>
6     <title>Gentoo GuideXML Guide</title>
7 swift 1.15
8     <author title="Author">
9 neysx 1.67 <mail link="neysx"/>
10 neysx 1.58 </author>
11     <author title="Author">
12 swift 1.15 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13     </author>
14 swift 1.19 <author title="Author"><!-- zhen@gentoo.org -->
15     John P. Davis
16 swift 1.15 </author>
17     <author title="Editor">
18     <mail link="peesh@gentoo.org">Jorge Paulo</mail>
19     </author>
20 swift 1.25 <author title="Editor">
21 nightmorph 1.66 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22 swift 1.25 </author>
23 nightmorph 1.69 <author title="Editor">
24     <mail link="nightmorph"/>
25     </author>
26 drobbins 1.1
27 swift 1.15 <abstract>
28     This guide shows you how to compose web documentation using the new lightweight
29 vapier 1.50 Gentoo GuideXML syntax. This syntax is the official format for Gentoo
30 swift 1.15 documentation, and this document itself was created using GuideXML. This guide
31     assumes a basic working knowledge of XML and HTML.
32 drobbins 1.1 </abstract>
33    
34 swift 1.31 <!-- The content of this document is licensed under the CC-BY-SA license -->
35 swift 1.46 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
36 swift 1.26 <license/>
37    
38 nightmorph 1.69 <version>10</version>
39     <date>2009-02-27</date>
40 drobbins 1.1
41     <chapter>
42 neysx 1.67 <title>GuideXML basics</title>
43 drobbins 1.1 <section>
44 neysx 1.67 <title>GuideXML design goals</title>
45 drobbins 1.1 <body>
46    
47 swift 1.15 <p>
48 neysx 1.67 The guideXML syntax is lightweight yet expressive, so that it is easy to
49 drobbins 1.1 learn yet also provides all the features we need for the creation of web
50     documentation. The number of tags is kept to a minimum -- just those we need.
51     This makes it easy to transform guide into other formats, such as DocBook
52 swift 1.15 XML/SGML or web-ready HTML.
53     </p>
54 drobbins 1.1
55 swift 1.15 <p>
56 neysx 1.67 The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML
57 swift 1.15 documents.
58     </p>
59 drobbins 1.1
60     </body>
61     </section>
62     <section>
63 swift 1.20 <title>Further Resources</title>
64 drobbins 1.1 <body>
65    
66 swift 1.15 <p>
67 neysx 1.34 If you are planning on contributing documentation to Gentoo, or you want to
68 neysx 1.52 test GuideXML, please read our <uri
69     link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
70     which contains tips and tricks for documentation development.
71     </p>
72    
73     <p>
74     You may want to look at the <uri link="?passthru=1">XML source</uri> of this
75     document while you read it.
76 drobbins 1.1 </p>
77    
78     </body>
79     </section>
80     </chapter>
81 swift 1.15
82 drobbins 1.1 <chapter>
83 neysx 1.67 <title>GuideXML</title>
84 drobbins 1.1 <section>
85     <title>Basic structure</title>
86     <body>
87    
88 swift 1.15 <p>
89 swift 1.36 Let's start learning the GuideXML syntax. We'll start with the the initial
90     tags used in a GuideXML document:
91 swift 1.15 </p>
92 drobbins 1.1
93     <pre caption="The initial part of a guide XML document">
94 cam 1.41 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
95 swift 1.25 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
96 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
97    
98 neysx 1.43 &lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt;
99 vapier 1.50 &lt;title&gt;<i>Gentoo Documentation Guide</i>&lt;/title&gt;
100 neysx 1.49
101 swift 1.33 &lt;author title="<i>Author</i>"&gt;
102     &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
103 drobbins 1.1 &lt;/author&gt;
104    
105 swift 1.15 &lt;abstract&gt;
106     <i>This guide shows you how to compose web documentation using
107     our new lightweight Gentoo GuideXML syntax. This syntax is the official
108 vapier 1.50 format for Gentoo web documentation, and this document itself was created
109 swift 1.15 using GuideXML.</i>
110     &lt;/abstract&gt;
111 drobbins 1.1
112 swift 1.27 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
113 swift 1.46 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
114 swift 1.14 &lt;license/&gt;
115    
116 drobbins 1.1 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
117 neysx 1.35 &lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
118 drobbins 1.1 </pre>
119    
120 swift 1.15 <p>
121 neysx 1.42 On the first lines, we see the requisite tag that identifies this as an XML
122     document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
123     will be automatically modified by the CVS server and helps to track revisions.
124 neysx 1.51 Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
125 neysx 1.67 enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
126     <br/>
127     The <c>link</c> attribute is optional and should preferably contain the
128     absolute path to the document relatively to the document root even though the
129     file name alone will work. It is only used to generate a link to a
130     printer-friendly version of your document and check whether a translation is
131     up-to-date. Our XSL back-engine passes the actual path to our XSL stylesheet.
132     The link attribute is only used as a fall-back value in case the XML is
133     processed by other means.
134     <br/>
135     The <c>lang</c> attribute should be used to specify the language code of your
136     document. It is used to format the date and insert strings like "<e>Note</e>",
137     "<e>Content</e>", etc. in the specified language. The default is English.
138 neysx 1.35 </p>
139    
140     <p>
141 drobbins 1.1 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
142 swift 1.15 guide document.
143     </p>
144 drobbins 1.1
145 swift 1.15 <p>
146     Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
147 drobbins 1.1 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
148 neysx 1.52 allows for an optional <c>title</c> element, used to specify the author's
149 drobbins 1.1 relationship to the document (author, co-author, editor, etc.). In this
150     particular example, the authors' names are enclosed in another tag -- a
151     <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
152 neysx 1.67 person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and at
153     least one <c>&lt;author&gt;</c> element is required per guide document.
154 drobbins 1.1 </p>
155    
156 swift 1.15 <p>
157     Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
158 drobbins 1.1 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
159 neysx 1.35 current version number, and the current version date (in YYYY-MM-DD format)
160     respectively. Dates that are invalid or not in the YYYY-MM-DD format will
161     appear verbatim in the rendered document.
162     </p>
163    
164     <p>
165 neysx 1.67 This sums up the tags that should appear at the beginning of a guide document.
166     Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these tags
167     shouldn't appear anywhere else except immediately inside the
168 drobbins 1.1 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
169 swift 1.15 required) that these tags appear before the content of the document.
170     </p>
171 swift 1.14
172 swift 1.15 <p>
173 neysx 1.38 Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document
174 neysx 1.49 under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
175 neysx 1.38 Commons - Attribution / Share Alike</uri> license as required by the <uri
176     link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
177 swift 1.15 </p>
178 drobbins 1.1
179     </body>
180     </section>
181     <section>
182     <title>Chapters and sections</title>
183     <body>
184 swift 1.15
185     <p>
186 neysx 1.37 Once the initial tags have been specified, you're ready to start adding the
187     structural elements of the document. Guide documents are divided into
188     chapters, and each chapter can hold one or more sections. Every chapter and
189     section has a title. Here's an example chapter with a single section,
190     consisting of a paragraph. If you append this XML to the XML in the <uri
191     link="#doc_chap2_pre1">previous excerpt</uri> and append a
192     <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid (if minimal)
193     guide document:
194 drobbins 1.1 </p>
195    
196 neysx 1.37 <pre caption="Minimal guide example">
197 drobbins 1.1 &lt;chapter&gt;
198     &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
199     &lt;section&gt;
200 swift 1.15 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
201     &lt;body&gt;
202    
203     &lt;p&gt;
204     <i>This is the actual text content of my section.</i>
205     &lt;/p&gt;
206    
207     &lt;/body&gt;
208 drobbins 1.1 &lt;/section&gt;
209     &lt;/chapter&gt;
210     </pre>
211    
212 swift 1.15 <p>
213     Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
214 drobbins 1.1 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
215     adding a <c>&lt;section&gt;</c> element. If you look inside the
216     <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
217     <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
218     is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
219     content of this particular section. We'll look at the tags that are allowed
220 swift 1.15 inside a <c>&lt;body&gt;</c> element in a bit.
221     </p>
222 drobbins 1.1
223 swift 1.15 <note>
224 neysx 1.67 A <c>&lt;guide&gt;</c> element must contain at least one <c>&lt;chapter&gt;</c>
225     elements, a <c>&lt;chapter&gt;</c> must contain at least one
226     <c>&lt;section&gt;</c> elements and a <c>&lt;section&gt;</c> element must
227     contain at least one <c>&lt;body&gt;</c> element.
228 swift 1.15 </note>
229 drobbins 1.1
230     </body>
231     </section>
232     <section>
233     <title>An example &lt;body&gt;</title>
234     <body>
235 swift 1.15
236 drobbins 1.1 <p>
237 neysx 1.37 Now, it's time to learn how to mark up actual content. Here's the XML code for
238     an example <c>&lt;body&gt;</c> element:
239 drobbins 1.1 </p>
240 swift 1.15
241 neysx 1.37 <pre caption="Example of a body element">
242 drobbins 1.1 &lt;p&gt;
243     This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
244 neysx 1.35 &lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
245 drobbins 1.1 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.
246     &lt;/p&gt;
247    
248 neysx 1.37 &lt;pre caption="Code Sample"&gt;
249 drobbins 1.1 This is text output or code.
250     # &lt;i&gt;this is user input&lt;/i&gt;
251    
252     Make HTML/XML easier to read by using selective emphasis:
253     &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
254    
255 neysx 1.58 &lt;comment&gt;(This is how to insert a comment into a code block)&lt;/comment&gt;
256 drobbins 1.1 &lt;/pre&gt;
257 swift 1.15
258     &lt;note&gt;
259     This is a note.
260     &lt;/note&gt;
261    
262     &lt;warn&gt;
263     This is a warning.
264     &lt;/warn&gt;
265    
266     &lt;impo&gt;
267     This is important.
268     &lt;/impo&gt;
269 drobbins 1.1 </pre>
270 swift 1.15
271     <p>
272 neysx 1.37 Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
273 swift 1.15 </p>
274 drobbins 1.1
275     <p>
276     This is a paragraph. <path>/etc/passwd</path> is a file.
277 swift 1.45 <uri>http://forums.gentoo.org</uri> is my favorite web site.
278 drobbins 1.1 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
279     </p>
280    
281 neysx 1.37 <pre caption="Code Sample">
282 drobbins 1.1 This is text output or code.
283     # <i>this is user input</i>
284    
285     Make HTML/XML easier to read by using selective emphasis:
286     &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
287    
288 neysx 1.58 <comment>(This is how to insert a comment into a code block)</comment>
289 drobbins 1.1 </pre>
290 swift 1.15
291     <note>
292     This is a note.
293     </note>
294    
295     <warn>
296     This is a warning.
297     </warn>
298    
299     <impo>
300     This is important.
301     </impo>
302    
303 drobbins 1.1 </body>
304     </section>
305     <section>
306     <title>The &lt;body&gt; tags</title>
307     <body>
308    
309 swift 1.15 <p>
310 neysx 1.52 We introduced a lot of new tags in the previous section -- here's what you need
311     to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block),
312     <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and <c>&lt;impo&gt;</c>
313     (important) tags all can contain one or more lines of text. Besides the
314     <c>&lt;table&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and
315     <c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
316     only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
317     Another thing -- these tags <e>should not</e> be stacked -- in other words,
318     don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
319     you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
320     exactly, making it well-suited for code excerpts. You must name the
321 neysx 1.53 <c>&lt;pre&gt;</c> tag with a <c>caption</c> attribute:
322 swift 1.15 </p>
323 swift 1.12
324 neysx 1.37 <pre caption="Named &lt;pre&gt;">
325 neysx 1.51 &lt;pre caption="Output of uptime"&gt;
326 swift 1.12 # &lt;i&gt;uptime&lt;/i&gt;
327     16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
328     &lt;/pre&gt;
329     </pre>
330 drobbins 1.1
331     </body>
332     </section>
333     <section>
334 neysx 1.52 <title>Epigraphs</title>
335     <body>
336    
337     <p by="Anonymous student">
338     Delegates from the original 13 states formed the Contented Congress. Thomas
339     Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
340     of Independence. Franklin discovered electricity by rubbing two cats backwards
341     and declared, "A horse divided against itself cannot stand." Franklin died in
342     1790 and is still dead.
343     </p>
344    
345     <p>
346     Epigraphs are sometimes used at the beginning of chapters to illustrate what is
347     to follow. It is simply a paragraph with a <c>by</c> attribute that contains
348     the signature.
349     </p>
350    
351     <pre caption="Short epigraph">
352     &lt;p by="Anonymous student"&gt;
353     Delegates from the original 13 states formed the...
354     &lt;/p&gt;
355     </pre>
356    
357     </body>
358     </section>
359     <section>
360     <title>
361 neysx 1.58 &lt;path&gt;, &lt;c&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
362 neysx 1.52 </title>
363 drobbins 1.1 <body>
364    
365 swift 1.15 <p>
366 neysx 1.52 The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
367     <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
368 neysx 1.58 <c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>.
369 swift 1.15 </p>
370 drobbins 1.1
371 swift 1.15 <p>
372     The <c>&lt;path&gt;</c> element is used to mark text that refers to an
373     <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
374 swift 1.45 <e>simple filename</e>. This element is generally rendered with a mono spaced
375 swift 1.15 font to offset it from the standard paragraph type.
376     </p>
377 drobbins 1.1
378 swift 1.15 <p>
379     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
380 drobbins 1.1 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
381     that they can type in that will perform some kind of action. For example, all
382     the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
383     element because they represent something that the user could type in that is
384     not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
385     quickly identify commands that they need to type in. Also, because
386     <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
387     necessary to surround user input with double-quotes</e>. For example, don't
388     refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
389 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
390     adorable!
391     </p>
392 drobbins 1.1
393 swift 1.15 <p>
394 neysx 1.51 As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some
395     text.
396     </p>
397    
398     <p>
399 swift 1.15 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
400 drobbins 1.1 I <e>really</e> should use semicolons more often. As you can see, this text is
401     offset from the regular paragraph type for emphasis. This helps to give your
402 swift 1.15 prose more <e>punch</e>!
403     </p>
404 drobbins 1.1
405 neysx 1.52 <p>
406     The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
407     <sub>subscript</sub> and <sup>superscript</sup>.
408     </p>
409    
410 drobbins 1.1 </body>
411     </section>
412     <section>
413 neysx 1.58 <title>Code samples and colour-coding</title>
414     <body>
415    
416     <p>
417     To improve the readability of code samples, the following tags are allowed
418     inside <c>&lt;pre&gt;</c> blocks:
419     </p>
420    
421     <dl>
422     <dt><c>&lt;i&gt;</c></dt>
423     <dd>Distinguishes user input from displayed text</dd>
424     <dt><c>&lt;comment&gt;</c></dt>
425     <dd>Comments relevant to the action(s) that appear after the comment</dd>
426     <dt><c>&lt;keyword&gt;</c></dt>
427     <dd>Denotes a keyword in the language used in the code sample
428     </dd>
429     <dt><c>&lt;ident&gt;</c></dt>
430     <dd>Used for an identifier
431     </dd>
432     <dt><c>&lt;const&gt;</c></dt>
433     <dd>Used for a constant
434     </dd>
435     <dt><c>&lt;stmt&gt;</c></dt>
436     <dd>Used for a statement
437     </dd>
438     <dt><c>&lt;var&gt;</c></dt>
439     <dd>Used for a variable
440     </dd>
441     </dl>
442    
443     <note>
444     Remember that all leading and trailing spaces, and line breaks in
445     <c>&lt;pre&gt;</c> blocks will appear in the displayed html page.
446     </note>
447    
448     <p>
449     Sample colour-coded <c>&lt;pre&gt;</c> block:
450     </p>
451    
452     <pre caption="My first ebuild">
453 nightmorph 1.69 <comment># Copyright 1999-2009 <b>Gentoo Foundation</b>
454 neysx 1.58 # Distributed under the terms of the GNU General Public License v2
455     # &#36;Header: $</comment>
456    
457     <ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
458     <ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
459     <ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
460    
461     <ident>LICENSE</ident>=<const>"GPL-2"</const>
462     <ident>SLOT</ident>=<const>"0"</const>
463     <ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
464     <ident>IUSE</ident>=<const>""</const>
465    
466     <stmt>src_compile()</stmt> {
467 nightmorph 1.69 <keyword>econf</keyword> --with-posix-regex
468 neysx 1.58 <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const>
469     }
470    
471     <stmt>src_install()</stmt> {
472     <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const>
473    
474     <keyword>dodoc</keyword> FAQ NEWS README
475     <keyword>dohtml</keyword> EXTENDING.html ctags.html
476     }
477     </pre>
478    
479     </body>
480     </section>
481     <section>
482 drobbins 1.1 <title>&lt;mail&gt; and &lt;uri&gt;</title>
483     <body>
484    
485 swift 1.15 <p>
486 neysx 1.51 We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
487     some text with a particular email address, and takes the form <c>&lt;mail
488 neysx 1.67 link="foo.bar@example.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the
489     email address, you can use <c>&lt;mail&gt;foo.bar@example.com&lt;/mail&gt;</c>, this
490     would be displayed as <mail>foo.bar@example.com</mail>.
491     </p>
492    
493     <p>
494     Shorter forms make it easier to use names and emails of Gentoo developers. Both
495     <c>&lt;mail&gt;neysx&lt;/mail&gt;</c> and <c>&lt;mail link="neysx"/&gt;</c>
496     would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email
497     with a different content than his full name, use the second form with some
498     content. For instance, use a dev's first name: <c>&lt;mail
499     link="neysx"&gt;Xavier&lt;/mail&gt;</c> appears as <mail
500     link="neysx">Xavier</mail>.
501     <br/>
502     This is particularly useful when you want to name a developer whose name
503     contains "funny" characters that you can't type.
504 swift 1.15 </p>
505 drobbins 1.1
506 swift 1.15 <p>
507 neysx 1.35 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
508     It has two forms -- the first can be used when you want to have the actual URI
509     displayed in the body text, such as this link to
510 neysx 1.67 <uri>http://forums.gentoo.org/</uri>. To create this link, I typed
511     <c>&lt;uri&gt;http://forums.gentoo.org/&lt;/uri&gt;</c>. The alternate form is
512 drobbins 1.1 when you want to associate a URI with some other text -- for example, <uri
513 neysx 1.67 link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create
514     <e>this</e> link, I typed <c>&lt;uri link="http://forums.gentoo.org/"&gt;the
515     Gentoo Forums&lt;/uri&gt;</c>. You don't need to write
516     <c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site.
517     For instance, a link to the <uri link="/doc/en/">documentation main index</uri>
518     should be simply <c>&lt;uri link="/doc/en/index.xml"&gt;documentation main
519     index&lt;/uri&gt;</c>. You can even omit <c>index.xml</c> when you link to a
520     directory index, e.g. <c>&lt;uri link="/doc/en/"&gt;documentation main
521     index&lt;/uri&gt;</c>. Leaving the trailing slash saves an extra HTTP request.
522     </p>
523    
524     <p>
525     You should not use a <c>&lt;uri&gt;</c> tag with a <c>link</c> attribute that
526     starts with <c>mailto:</c>. In this case, use a <c>&lt;mail&gt;</c> tag.
527     </p>
528    
529     <p>
530     Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here
531     syndrome</uri> as recommended by the <uri
532     link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
533 drobbins 1.1 </p>
534    
535     </body>
536     </section>
537     <section>
538     <title>Figures</title>
539     <body>
540    
541 swift 1.15 <p>
542     Here's how to insert a figure into a document -- <c>&lt;figure
543 drobbins 1.1 link="mygfx.png" short="my picture" caption="my favorite picture of all
544 neysx 1.52 time"/&gt;</c>. The <c>link</c> attribute points to the actual graphic image,
545     the <c>short</c> attribute specifies a short description (currently used for
546     the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
547 drobbins 1.1 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
548 swift 1.15 for adding images without captions, borders, etc.
549     </p>
550 drobbins 1.1
551     </body>
552     </section>
553     <section>
554 neysx 1.52 <title>Tables</title>
555 drobbins 1.1 <body>
556    
557 swift 1.15 <p>
558 neysx 1.67 GuideXML supports a simplified table syntax similar to that of HTML. To start a
559 neysx 1.51 table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
560 neysx 1.67 tag. However, for inserting actual table data, we <e>don't</e> support the HTML
561     &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
562 drobbins 1.1 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
563 neysx 1.51 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
564     -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
565     first row.
566 drobbins 1.1 </p>
567    
568 swift 1.15 <p>
569 neysx 1.60 Besides, both table headers (<c>&lt;th&gt;</c>) and table items
570     (<c>&lt;ti&gt;</c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to
571 neysx 1.61 span their content across rows, columns or both.
572     </p>
573    
574     <p>
575 neysx 1.68 Furthermore, table cells (<c>&lt;ti&gt;</c> &amp; <c>&lt;th&gt;</c>) can be
576     right-aligned, left-aligned or centered with the <c>align</c> attribute.
577 neysx 1.52 </p>
578    
579     <table>
580     <tr>
581 neysx 1.68 <th align="center" colspan="4">This title spans 4 columns</th>
582 neysx 1.52 </tr>
583     <tr>
584 neysx 1.59 <th rowspan="6">This title spans 6 rows</th>
585 neysx 1.52 <ti>Item A1</ti>
586     <ti>Item A2</ti>
587     <ti>Item A3</ti>
588     </tr>
589     <tr>
590 neysx 1.61 <ti align="center">Item B1</ti>
591 neysx 1.68 <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
592 neysx 1.52 </tr>
593     <tr>
594 neysx 1.61 <ti align="right">Item C1</ti>
595 neysx 1.52 </tr>
596 neysx 1.59 <tr>
597 neysx 1.61 <ti colspan="3" align="center">Item D1..D3</ti>
598 neysx 1.59 </tr>
599     <tr>
600     <ti rowspan="2">Item E1..F1</ti>
601 neysx 1.61 <ti colspan="2" align="right">Item E2..E3</ti>
602 neysx 1.59 </tr>
603     <tr>
604 neysx 1.61 <ti colspan="2" align="right">Item F2..F3</ti>
605 neysx 1.59 </tr>
606 neysx 1.52 </table>
607    
608     </body>
609     </section>
610     <section>
611     <title>Lists</title>
612     <body>
613    
614     <p>
615 swift 1.39 To create ordered or unordered lists, simply use the XHTML-style
616 neysx 1.52 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
617     appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
618     that you can have lists inside lists. Don't forget that you are writing XML and
619     that you must close all tags including list items unlike in HTML.
620 swift 1.15 </p>
621 drobbins 1.1
622 neysx 1.52 <p>
623     Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that
624     neither the definition term tag (<c>&lt;dt&gt;</c>) nor the definition data tag
625     (<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
626 neysx 1.53 admonitions. A definition list comprises:
627 neysx 1.52 </p>
628    
629     <dl>
630     <dt><c>&lt;dl&gt;</c></dt>
631     <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
632     <dt><c>&lt;dt&gt;</c></dt>
633     <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
634     <dt><c>&lt;dd&gt;</c></dt>
635     <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
636     </dl>
637    
638     <p>
639     The following list copied from <uri
640     link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
641     that a definition list can contain ordered and unordered lists. It may not
642     contain another definition list though.
643     </p>
644    
645     <dl>
646     <dt><b>The ingredients:</b></dt>
647     <dd>
648     <ul>
649     <li>100 g. flour</li>
650     <li>10 g. sugar</li>
651     <li>1 cup water</li>
652     <li>2 eggs</li>
653     <li>salt, pepper</li>
654     </ul>
655     </dd>
656     <dt><b>The procedure:</b></dt>
657     <dd>
658     <ol>
659 neysx 1.53 <li>Mix dry ingredients thoroughly</li>
660     <li>Pour in wet ingredients</li>
661     <li>Mix for 10 minutes</li>
662     <li>Bake for one hour at 300 degrees</li>
663 neysx 1.52 </ol>
664     </dd>
665     <dt><b>Notes:</b></dt>
666 neysx 1.53 <dd>The recipe may be improved by adding raisins</dd>
667 neysx 1.52 </dl>
668    
669 drobbins 1.1 </body>
670     </section>
671     <section>
672     <title>Intra-document references</title>
673     <body>
674    
675 swift 1.15 <p>
676 neysx 1.67 GuideXML makes it really easy to reference other parts of the document using
677 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
678     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
679     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
680     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
681 neysx 1.67 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type
682     <c>&lt;uri link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer
683     to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type
684     <c>&lt;uri link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.
685 swift 1.17 </p>
686 swift 1.23
687     <p>
688     However, some guides change often and using such "counting" can lead to broken
689     links. In order to cope with this, you can define a name for a
690 neysx 1.47 <c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
691     the <c>id</c> attribute, and then point to that attribute, like this:
692 swift 1.23 </p>
693    
694     <pre caption="Using the id attribute">
695     &lt;chapter id="foo"&gt;
696     &lt;title&gt;This is foo!&lt;/title&gt;
697     ...
698     &lt;p&gt;
699     More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
700     &lt;/p&gt;
701     </pre>
702 swift 1.17
703     </body>
704     </section>
705 neysx 1.51 <section>
706     <title>Disclaimers and obsolete documents</title>
707     <body>
708    
709     <p>
710 alin 1.54 A <c>disclaimer</c> attribute can be applied to guides and handbooks to display
711     a predefined disclaimer at the top of the document. The available disclaimers
712     are:
713 neysx 1.51 </p>
714    
715     <ul>
716     <li>
717     <b>articles</b> is used for <uri link="/doc/en/articles/">republished
718     articles</uri>
719     </li>
720     <li>
721     <b>draft</b> is used to indicate a document is still being worked on and
722     should not be considered official
723     </li>
724     <li>
725     <b>oldbook</b> is used on old handbooks to indicate they are not maintained
726     anymore
727     </li>
728     <li><b>obsolete</b> is used to mark a document as obsolete.</li>
729     </ul>
730    
731     <p>
732     When marking a document as obsolete, you might want to add a link to a new
733     version. The <c>redirect</c> attribute does just that. The user might be
734     automatically redirected to the new page but you should not rely on that
735     behaviour.
736     </p>
737    
738     <pre caption="Disclaimer sample">
739     &lt;?xml version="1.0" encoding="UTF-8"?&gt;
740     &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
741     &lt;!-- &#36;Header&#36; --&gt;
742    
743 neysx 1.67 &lt;guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
744 neysx 1.51 &lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
745    
746     &lt;author title="Author"&gt;
747     ...
748     </pre>
749    
750     </body>
751     </section>
752 neysx 1.67 <section>
753     <title>FAQs</title>
754     <body>
755    
756     <p>
757     FAQ documents need to start with a list of questions with links to their
758     answers. Creating such a list is both time-consuming and error-prone. The list
759     can be created automatically if you use a <c>faqindex</c> element as the first
760     chapter of your document. This element has the same structure as a
761     <c>chapter</c> to allow some introductory text. The structure of the document
762     is expected to be split into chapters (at least one chapter) containing
763     sections, each section containing one question specified in its <c>title</c>
764     element with the answer in its <c>body</c>. The FAQ index will appear as one
765     section per chapter and one link per question.
766     </p>
767    
768     <p>
769     A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri
770     link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above
771     obvious.
772     </p>
773    
774     </body>
775     </section>
776     </chapter>
777    
778     <chapter>
779     <title>Handbook Format</title>
780     <section>
781     <title>Guide vs Book</title>
782     <body>
783    
784     <p>
785     For high-volume documentation, such as the <uri
786     link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
787     broader format was needed. We designed a GuideXML-compatible enhancement that
788     allows us to write modular and multi-page documentation.
789     </p>
790    
791     </body>
792     </section>
793     <section>
794     <title>Main File</title>
795     <body>
796    
797     <p>
798     The first change is the need for a "master" document. This document contains no
799     real content, but links to the individual documentation modules. The syntax
800     doesn't differ much from GuideXML:
801     </p>
802    
803     <pre caption="Example book usage">
804     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
805     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
806     &lt;!-- &#36;Header&#36; --&gt;
807    
808     &lt;<i>book</i>&gt;
809     &lt;title&gt;Example Book Usage&lt;/title&gt;
810    
811     &lt;author...&gt;
812     ...
813     &lt;/author&gt;
814    
815     &lt;abstract&gt;
816     ...
817     &lt;/abstract&gt;
818    
819     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
820     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
821     &lt;license/&gt;
822    
823     &lt;version&gt;...&lt;/version&gt;
824     &lt;date&gt;...&lt;/date&gt;
825     </pre>
826    
827     <p>
828     So far no real differences (except for the <c>&lt;book&gt;</c> instead of
829     <c>&lt;guide&gt;</c> tag). Instead of starting with the individual
830     <c>&lt;chapter&gt;</c>s, you define a <c>&lt;part&gt;</c>, which is the
831     equivalent of a separate part in a book:
832     </p>
833    
834     <pre caption="Defining a part">
835     &lt;part&gt;
836     &lt;title&gt;Part One&lt;/title&gt;
837     &lt;abstract&gt;
838     ...
839     &lt;/abstract&gt;
840    
841     <comment>(Defining the several chapters)</comment>
842     &lt;/part&gt;
843     </pre>
844    
845     <p>
846     Each part is accompanied by a <c>&lt;title&gt;</c> and an
847     <c>&lt;abstract&gt;</c> which gives a small introduction to the part.
848     </p>
849    
850     <p>
851     Inside each part, you define the individual <c>&lt;chapter&gt;</c>s. Each
852     chapter <e>must</e> be a separate document. As a result it is no surprise that
853     a special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
854     document.
855     </p>
856    
857     <pre caption="Defining a chapter">
858     &lt;chapter&gt;
859     &lt;title&gt;Chapter One&lt;/title&gt;
860    
861     &lt;include href="path/to/chapter-one.xml"/&gt;
862    
863     &lt;/chapter&gt;
864     </pre>
865    
866     </body>
867     </section>
868     <section>
869     <title>Designing the Individual Chapters</title>
870     <body>
871    
872     <p>
873     The content of an individual chapter is structured as follows:
874     </p>
875    
876     <pre caption="Chapter Syntax">
877     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
878     &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
879     &lt;!-- &#36;Header&#36; --&gt;
880    
881     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
882     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
883    
884     &lt;sections&gt;
885    
886     &lt;abstract&gt;
887     This is a small explanation on chapter one.
888     &lt;/abstract&gt;
889    
890     &lt;version&gt;...&lt;/version&gt;
891     &lt;date&gt;...&lt;/date&gt;
892    
893     <comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
894    
895     &lt;/sections&gt;
896     </pre>
897    
898     <p>
899     Inside each chapter you can define <c>&lt;section&gt;</c>s (equivalent of
900     <c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>s (equivalent
901     of <c>&lt;section&gt;</c> in a Guide).
902     </p>
903    
904     <p>
905     Each individual chapter should have its own date and version elements. The
906     latest date of all chapters and master document will be displayed when a user
907     browses through all parts of the book.
908     </p>
909    
910     </body>
911     </section>
912 swift 1.17 </chapter>
913    
914     <chapter>
915 neysx 1.67 <title>Advanced Handbook Features</title>
916     <section>
917     <title>Global Values</title>
918     <body>
919    
920     <p>
921     Sometimes, the same values are repeated many times in several parts of a
922     handbook. Global search and replace operations tend to forget some or introduce
923     unwanted changes. Besides, it can be useful to define different values to be
924     used in shared chapters depending on which handbook includes the chapter.
925     </p>
926    
927     <p>
928     Global values can be defined in a handbook master file and used in all included
929     chapters.
930     </p>
931    
932     <p>
933     To define global values, add a <c>&lt;values&gt;</c> element to the handbook
934     master file. Each value is then defined in a <c>&lt;key&gt;</c> element whose
935     <c>id</c> attribute identifies the value, i.e. it is the name of your variable.
936     The content of the <c>&lt;key&gt;</c> is its value.
937     </p>
938    
939     <p>
940     The following example defines three values in a handbook master file:
941     </p>
942    
943     <pre caption="Define values in a handbook">
944     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
945     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
946     &lt;!-- &#36;Header&#36; --&gt;
947    
948     &lt;book&gt;
949     &lt;title&gt;Example Book Usage&lt;/title&gt;
950    
951     <i>&lt;values>
952     &lt;key id="arch"&gt;x86&lt;/key&gt;
953     &lt;key id="min-cd-name"&gt;install-x86-minimal-2007.0-r1.iso&lt;/key&gt;
954     &lt;key id="min-cd-size"&gt;57&lt;/key&gt;
955     &lt;/values&gt;</i>
956    
957     &lt;author...&gt;
958     ...
959     &lt;/author&gt;
960    
961     ...
962     </pre>
963    
964     <p>
965     The defined values can then be used throughout the handbook with the in-line
966     <c>&lt;keyval id="key_id"/&gt;</c> element. Specify the name of the key in its
967     <c>id</c> attribute, e.g. &lt;keyval id="min-cd-name"/&gt; would be replaced by
968     "install-x86-minimal-2007.0-r1.iso" in our example.
969     </p>
970    
971     <pre caption="Using defined values">
972     &lt;p&gt;
973     The Minimal Installation CD is called &lt;c&gt;<i>&lt;keyval id="min-cd-name"/&gt;</i>&lt;/c&gt;
974     and takes up only <i>&lt;keyval id="min-cd-size"/&gt;</i> MB of diskspace. You can use this
975     Installation CD to install Gentoo, but &lt;e&gt;only&lt;/e&gt; with a working Internet
976     connection.
977     &lt;/p&gt;
978     </pre>
979    
980     <p>
981     To make life easier on our translators, only use actual values, i.e. content
982     that does not need to be translated. For instance, we defined the
983     <c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>.
984     </p>
985    
986     </body>
987     </section>
988     <section>
989     <title>Conditional Elements</title>
990     <body>
991    
992     <p>
993     Chapters that are shared by several handbooks such as our <uri
994     link="/doc/en/handbook/">Installation Handbooks</uri> often have small
995     differences depending on which handbook includes them. Instead of adding
996     content that is irrelevant to some handbooks, authors can add a condition to
997     the following elements: <c>&lt;section&gt;</c>, <c>&lt;subsection&gt;</c>,
998     <c>&lt;body&gt;</c>, <c>&lt;note&gt;</c>, <c>&lt;impo&gt;</c>,
999     <c>&lt;warn&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;p&gt;</c>,
1000     <c>&lt;table&gt;</c>, <c>&lt;tr&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>
1001     and <c>&lt;li&gt;</c>.
1002     </p>
1003    
1004     <p>
1005     The condition must be an <uri
1006     link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be
1007     evaluated when transforming the XML. If it evaluates to <c>true</c>, the
1008     element is processed, if not, it is ignored. The condition is specified in a
1009     <c>test</c> attribute.
1010     </p>
1011    
1012     <p>
1013     The following example uses the <c>arch</c> value that is defined in each
1014     handbook master file to condition some content:
1015     </p>
1016    
1017     <pre caption="Using conditional elements">
1018     &lt;body test="contains('AMD64 x86',func:keyval('arch'))"&gt;
1019    
1020     &lt;p&gt;
1021     This paragraph applies to both x86 and AMD64 architectures.
1022     &lt;/p&gt;
1023    
1024     &lt;p test="func:keyval('arch')='x86'"&gt;
1025     This paragraph only applies to the x86 architecture.
1026     &lt;/p&gt;
1027    
1028     &lt;p test="func:keyval('arch')='AMD64'"&gt;
1029     This paragraph only applies to the AMD64 architecture.
1030     &lt;/p&gt;
1031    
1032     &lt;p test="func:keyval('arch')='PPC'"&gt;
1033     This paragraph will never be seen!
1034     The whole body is skipped because of the first condition.
1035     &lt;/p&gt;
1036    
1037     &lt;/body&gt;
1038    
1039     &lt;body test="contains('AMD64 PPC64',func:keyval('arch'))"&gt;
1040    
1041     &lt;p&gt;
1042     This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because
1043     the 'AMD64 PPC64' string does contain 'PPC'.
1044     &lt;/p&gt;
1045    
1046     &lt;note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"&gt;
1047     This note only applies to the AMD64 and PPC64 architectures.
1048     &lt;/note&gt;
1049    
1050     &lt;/body&gt;
1051     </pre>
1052    
1053     </body>
1054     </section>
1055     </chapter>
1056    
1057     <chapter id="codingstyle">
1058 swift 1.17 <title>Coding Style</title>
1059     <section>
1060     <title>Introduction</title>
1061     <body>
1062    
1063     <p>
1064     Since all Gentoo Documentation is a joint effort and several people will
1065     most likely change existing documentation, a coding style is needed.
1066     A coding style contains two sections. The first one is regarding
1067 swift 1.45 internal coding - how the XML-tags are placed. The second one is
1068 swift 1.17 regarding the content - how not to confuse the reader.
1069     </p>
1070    
1071     <p>
1072     Both sections are described next.
1073     </p>
1074    
1075     </body>
1076     </section>
1077     <section>
1078     <title>Internal Coding Style</title>
1079     <body>
1080    
1081     <p>
1082     <b>Newlines</b> must be placed immediately after <e>every</e>
1083     GuideXML-tag (both opening as closing), except for:
1084     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
1085     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
1086     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
1087 swift 1.44 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
1088 neysx 1.37 <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
1089 swift 1.17 </p>
1090    
1091     <p>
1092     <b>Blank lines</b> must be placed immediately after <e>every</e>
1093     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
1094     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
1095 swift 1.18 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
1096     <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
1097     <c>&lt;impo&gt;</c> (opening tags only).
1098 swift 1.17 </p>
1099    
1100     <p>
1101     <b>Word-wrapping</b> must be applied at 80 characters except inside
1102 neysx 1.51 <c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
1103     choice (for instance when a URL exceeds the maximum amount of characters). The
1104     editor must then wrap whenever the first whitespace occurs. You should try to
1105     keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
1106     columns to help console users.
1107 swift 1.17 </p>
1108    
1109     <p>
1110 neysx 1.51 <b>Indentation</b> may not be used, except with the XML-constructs of which the
1111     parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
1112 neysx 1.53 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>, <c>&lt;dl&gt;</c>, and
1113     <c>&lt;author&gt;</c>. If indentation is used, it <e>must</e> be two spaces for
1114     each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
1115     Besides, tabs are not allowed in GuideXML documents.
1116 swift 1.17 </p>
1117    
1118     <p>
1119 neysx 1.53 In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>,
1120 neysx 1.57 <c>&lt;li&gt;</c> or <c>&lt;dd&gt;</c> constructs, indentation must be used for
1121 neysx 1.53 the content.
1122 swift 1.17 </p>
1123    
1124     <p>
1125     An example for indentation is:
1126     </p>
1127    
1128 neysx 1.37 <pre caption="Indentation Example">
1129 swift 1.17 &lt;table&gt;
1130     &lt;tr&gt;
1131     &lt;th&gt;Foo&lt;/th&gt;
1132     &lt;th&gt;Bar&lt;/th&gt;
1133     &lt;/tr&gt;
1134     &lt;tr&gt;
1135 swift 1.48 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
1136 swift 1.17 &lt;ti&gt;
1137     In case text cannot be shown within an 80-character wide line, you
1138 swift 1.48 must use indentation if the parent tag allows it
1139 swift 1.17 &lt;/ti&gt;
1140     &lt;/tr&gt;
1141     &lt;/table&gt;
1142    
1143     &lt;ul&gt;
1144     &lt;li&gt;First option&lt;/li&gt;
1145     &lt;li&gt;Second option&lt;/li&gt;
1146     &lt;/ul&gt;
1147     </pre>
1148    
1149     <p>
1150 neysx 1.53 <b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
1151     and the attribute value. As an example:
1152 swift 1.17 </p>
1153    
1154     <pre caption="Attributes">
1155     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
1156     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
1157     </pre>
1158    
1159     </body>
1160     </section>
1161     <section>
1162     <title>External Coding Style</title>
1163     <body>
1164    
1165     <p>
1166 neysx 1.53 Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c>,
1167     <c>&lt;ol&gt;</c>) and <c>&lt;dl&gt;</c>, periods (".") should not be used
1168     unless multiple sentences are used. In that case, every sentence should end
1169     with a period (or other reading marks).
1170 swift 1.17 </p>
1171    
1172     <p>
1173     Every sentence, including those inside tables and listings, should start
1174     with a capital letter.
1175     </p>
1176    
1177     <pre caption="Periods and capital letters">
1178     &lt;ul&gt;
1179     &lt;li&gt;No period&lt;/li&gt;
1180     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
1181     &lt;/ul&gt;
1182     </pre>
1183    
1184     <p>
1185     Code Listings should <e>always</e> have a <c>caption</c>.
1186     </p>
1187    
1188     <p>
1189     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
1190 neysx 1.35 possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
1191     Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
1192 swift 1.15 </p>
1193 swift 1.18
1194     <p>
1195 neysx 1.37 When you comment something inside a <c>&lt;pre&gt;</c> construct, use
1196     <c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
1197     that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
1198     for C code, etc.) Also place the comment <e>before</e> the subject of the
1199     comment.
1200 swift 1.18 </p>
1201    
1202     <pre caption="Comment example">
1203     <comment>(Substitute "john" with your user name)</comment>
1204     # <i>id john</i>
1205     </pre>
1206 drobbins 1.1
1207     </body>
1208     </section>
1209     </chapter>
1210 swift 1.15
1211 drobbins 1.1 <chapter>
1212     <title>Resources</title>
1213     <section>
1214 swift 1.15 <title>Start writing</title>
1215     <body>
1216    
1217     <p>
1218 neysx 1.67 GuideXML has been specially designed to be "lean and mean" so that developers
1219     can spend more time writing documentation and less time learning the actual XML
1220 swift 1.15 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
1221 neysx 1.67 to start writing quality Gentoo documentation. You might be interested in our
1222     <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips
1223     &amp; Tricks</uri>. If you'd like to help (or have any questions about
1224     GuideXML), please post a message to the <uri
1225     link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like
1226     to tackle. Have fun!
1227 swift 1.15 </p>
1228    
1229     </body>
1230 drobbins 1.1 </section>
1231     </chapter>
1232     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20