/[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.71 - (hide annotations) (download) (as text)
Tue Nov 29 19:02:45 2011 UTC (2 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.70: +14 -12 lines
File MIME type: application/xml
Document the use of the "<license version="3.0"/>" tag

With CC-BY-SA 3.0 now allowed for documents, we document this approach in the XML Guide.

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

  ViewVC Help
Powered by ViewVC 1.1.20