/[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.67 - (hide annotations) (download) (as text)
Thu Oct 4 19:37:23 2007 UTC (7 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.66: +391 -196 lines
File MIME type: application/xml
Documented recent and much less recent features:
 . shortcut for Gentoo devs in <mail>
 . @link is not compulsory
 . handbook values & conditionals
 . <faqindex>
Used GuideXML more consistently

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

  ViewVC Help
Powered by ViewVC 1.1.20