/[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.68 - (hide annotations) (download) (as text)
Sun Mar 9 13:13:15 2008 UTC (6 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.67: +7 -8 lines
File MIME type: application/xml
Allow align on <th> for rane

1 cam 1.41 <?xml version="1.0" encoding="UTF-8"?>
2 neysx 1.68 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.67 2007/10/04 19:37:23 neysx Exp $ -->
3 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 neysx 1.67 <guide>
6     <title>Gentoo GuideXML Guide</title>
7 swift 1.15
8     <author title="Author">
9 neysx 1.67 <mail link="neysx"/>
10 neysx 1.58 </author>
11     <author title="Author">
12 swift 1.15 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13     </author>
14 swift 1.19 <author title="Author"><!-- zhen@gentoo.org -->
15     John P. Davis
16 swift 1.15 </author>
17     <author title="Editor">
18     <mail link="peesh@gentoo.org">Jorge Paulo</mail>
19     </author>
20 swift 1.25 <author title="Editor">
21 nightmorph 1.66 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22 swift 1.25 </author>
23 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.68 <version>9</version>
36     <date>2008-03-09</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 neysx 1.68 Furthermore, table cells (<c>&lt;ti&gt;</c> &amp; <c>&lt;th&gt;</c>) can be
573     right-aligned, left-aligned or centered with the <c>align</c> attribute.
574 neysx 1.52 </p>
575    
576     <table>
577     <tr>
578 neysx 1.68 <th align="center" colspan="4">This title spans 4 columns</th>
579 neysx 1.52 </tr>
580     <tr>
581 neysx 1.59 <th rowspan="6">This title spans 6 rows</th>
582 neysx 1.52 <ti>Item A1</ti>
583     <ti>Item A2</ti>
584     <ti>Item A3</ti>
585     </tr>
586     <tr>
587 neysx 1.61 <ti align="center">Item B1</ti>
588 neysx 1.68 <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
589 neysx 1.52 </tr>
590     <tr>
591 neysx 1.61 <ti align="right">Item C1</ti>
592 neysx 1.52 </tr>
593 neysx 1.59 <tr>
594 neysx 1.61 <ti colspan="3" align="center">Item D1..D3</ti>
595 neysx 1.59 </tr>
596     <tr>
597     <ti rowspan="2">Item E1..F1</ti>
598 neysx 1.61 <ti colspan="2" align="right">Item E2..E3</ti>
599 neysx 1.59 </tr>
600     <tr>
601 neysx 1.61 <ti colspan="2" align="right">Item F2..F3</ti>
602 neysx 1.59 </tr>
603 neysx 1.52 </table>
604    
605     </body>
606     </section>
607     <section>
608     <title>Lists</title>
609     <body>
610    
611     <p>
612 swift 1.39 To create ordered or unordered lists, simply use the XHTML-style
613 neysx 1.52 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
614     appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
615     that you can have lists inside lists. Don't forget that you are writing XML and
616     that you must close all tags including list items unlike in HTML.
617 swift 1.15 </p>
618 drobbins 1.1
619 neysx 1.52 <p>
620     Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that
621     neither the definition term tag (<c>&lt;dt&gt;</c>) nor the definition data tag
622     (<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
623 neysx 1.53 admonitions. A definition list comprises:
624 neysx 1.52 </p>
625    
626     <dl>
627     <dt><c>&lt;dl&gt;</c></dt>
628     <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
629     <dt><c>&lt;dt&gt;</c></dt>
630     <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
631     <dt><c>&lt;dd&gt;</c></dt>
632     <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
633     </dl>
634    
635     <p>
636     The following list copied from <uri
637     link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
638     that a definition list can contain ordered and unordered lists. It may not
639     contain another definition list though.
640     </p>
641    
642     <dl>
643     <dt><b>The ingredients:</b></dt>
644     <dd>
645     <ul>
646     <li>100 g. flour</li>
647     <li>10 g. sugar</li>
648     <li>1 cup water</li>
649     <li>2 eggs</li>
650     <li>salt, pepper</li>
651     </ul>
652     </dd>
653     <dt><b>The procedure:</b></dt>
654     <dd>
655     <ol>
656 neysx 1.53 <li>Mix dry ingredients thoroughly</li>
657     <li>Pour in wet ingredients</li>
658     <li>Mix for 10 minutes</li>
659     <li>Bake for one hour at 300 degrees</li>
660 neysx 1.52 </ol>
661     </dd>
662     <dt><b>Notes:</b></dt>
663 neysx 1.53 <dd>The recipe may be improved by adding raisins</dd>
664 neysx 1.52 </dl>
665    
666 drobbins 1.1 </body>
667     </section>
668     <section>
669     <title>Intra-document references</title>
670     <body>
671    
672 swift 1.15 <p>
673 neysx 1.67 GuideXML makes it really easy to reference other parts of the document using
674 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
675     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
676     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
677     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
678 neysx 1.67 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type
679     <c>&lt;uri link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer
680     to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type
681     <c>&lt;uri link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.
682 swift 1.17 </p>
683 swift 1.23
684     <p>
685     However, some guides change often and using such "counting" can lead to broken
686     links. In order to cope with this, you can define a name for a
687 neysx 1.47 <c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
688     the <c>id</c> attribute, and then point to that attribute, like this:
689 swift 1.23 </p>
690    
691     <pre caption="Using the id attribute">
692     &lt;chapter id="foo"&gt;
693     &lt;title&gt;This is foo!&lt;/title&gt;
694     ...
695     &lt;p&gt;
696     More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
697     &lt;/p&gt;
698     </pre>
699 swift 1.17
700     </body>
701     </section>
702 neysx 1.51 <section>
703     <title>Disclaimers and obsolete documents</title>
704     <body>
705    
706     <p>
707 alin 1.54 A <c>disclaimer</c> attribute can be applied to guides and handbooks to display
708     a predefined disclaimer at the top of the document. The available disclaimers
709     are:
710 neysx 1.51 </p>
711    
712     <ul>
713     <li>
714     <b>articles</b> is used for <uri link="/doc/en/articles/">republished
715     articles</uri>
716     </li>
717     <li>
718     <b>draft</b> is used to indicate a document is still being worked on and
719     should not be considered official
720     </li>
721     <li>
722     <b>oldbook</b> is used on old handbooks to indicate they are not maintained
723     anymore
724     </li>
725     <li><b>obsolete</b> is used to mark a document as obsolete.</li>
726     </ul>
727    
728     <p>
729     When marking a document as obsolete, you might want to add a link to a new
730     version. The <c>redirect</c> attribute does just that. The user might be
731     automatically redirected to the new page but you should not rely on that
732     behaviour.
733     </p>
734    
735     <pre caption="Disclaimer sample">
736     &lt;?xml version="1.0" encoding="UTF-8"?&gt;
737     &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
738     &lt;!-- &#36;Header&#36; --&gt;
739    
740 neysx 1.67 &lt;guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
741 neysx 1.51 &lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
742    
743     &lt;author title="Author"&gt;
744     ...
745     </pre>
746    
747     </body>
748     </section>
749 neysx 1.67 <section>
750     <title>FAQs</title>
751     <body>
752    
753     <p>
754     FAQ documents need to start with a list of questions with links to their
755     answers. Creating such a list is both time-consuming and error-prone. The list
756     can be created automatically if you use a <c>faqindex</c> element as the first
757     chapter of your document. This element has the same structure as a
758     <c>chapter</c> to allow some introductory text. The structure of the document
759     is expected to be split into chapters (at least one chapter) containing
760     sections, each section containing one question specified in its <c>title</c>
761     element with the answer in its <c>body</c>. The FAQ index will appear as one
762     section per chapter and one link per question.
763     </p>
764    
765     <p>
766     A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri
767     link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above
768     obvious.
769     </p>
770    
771     </body>
772     </section>
773     </chapter>
774    
775     <chapter>
776     <title>Handbook Format</title>
777     <section>
778     <title>Guide vs Book</title>
779     <body>
780    
781     <p>
782     For high-volume documentation, such as the <uri
783     link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
784     broader format was needed. We designed a GuideXML-compatible enhancement that
785     allows us to write modular and multi-page documentation.
786     </p>
787    
788     </body>
789     </section>
790     <section>
791     <title>Main File</title>
792     <body>
793    
794     <p>
795     The first change is the need for a "master" document. This document contains no
796     real content, but links to the individual documentation modules. The syntax
797     doesn't differ much from GuideXML:
798     </p>
799    
800     <pre caption="Example book usage">
801     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
802     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
803     &lt;!-- &#36;Header&#36; --&gt;
804    
805     &lt;<i>book</i>&gt;
806     &lt;title&gt;Example Book Usage&lt;/title&gt;
807    
808     &lt;author...&gt;
809     ...
810     &lt;/author&gt;
811    
812     &lt;abstract&gt;
813     ...
814     &lt;/abstract&gt;
815    
816     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
817     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
818     &lt;license/&gt;
819    
820     &lt;version&gt;...&lt;/version&gt;
821     &lt;date&gt;...&lt;/date&gt;
822     </pre>
823    
824     <p>
825     So far no real differences (except for the <c>&lt;book&gt;</c> instead of
826     <c>&lt;guide&gt;</c> tag). Instead of starting with the individual
827     <c>&lt;chapter&gt;</c>s, you define a <c>&lt;part&gt;</c>, which is the
828     equivalent of a separate part in a book:
829     </p>
830    
831     <pre caption="Defining a part">
832     &lt;part&gt;
833     &lt;title&gt;Part One&lt;/title&gt;
834     &lt;abstract&gt;
835     ...
836     &lt;/abstract&gt;
837    
838     <comment>(Defining the several chapters)</comment>
839     &lt;/part&gt;
840     </pre>
841    
842     <p>
843     Each part is accompanied by a <c>&lt;title&gt;</c> and an
844     <c>&lt;abstract&gt;</c> which gives a small introduction to the part.
845     </p>
846    
847     <p>
848     Inside each part, you define the individual <c>&lt;chapter&gt;</c>s. Each
849     chapter <e>must</e> be a separate document. As a result it is no surprise that
850     a special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
851     document.
852     </p>
853    
854     <pre caption="Defining a chapter">
855     &lt;chapter&gt;
856     &lt;title&gt;Chapter One&lt;/title&gt;
857    
858     &lt;include href="path/to/chapter-one.xml"/&gt;
859    
860     &lt;/chapter&gt;
861     </pre>
862    
863     </body>
864     </section>
865     <section>
866     <title>Designing the Individual Chapters</title>
867     <body>
868    
869     <p>
870     The content of an individual chapter is structured as follows:
871     </p>
872    
873     <pre caption="Chapter Syntax">
874     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
875     &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
876     &lt;!-- &#36;Header&#36; --&gt;
877    
878     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
879     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
880    
881     &lt;sections&gt;
882    
883     &lt;abstract&gt;
884     This is a small explanation on chapter one.
885     &lt;/abstract&gt;
886    
887     &lt;version&gt;...&lt;/version&gt;
888     &lt;date&gt;...&lt;/date&gt;
889    
890     <comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
891    
892     &lt;/sections&gt;
893     </pre>
894    
895     <p>
896     Inside each chapter you can define <c>&lt;section&gt;</c>s (equivalent of
897     <c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>s (equivalent
898     of <c>&lt;section&gt;</c> in a Guide).
899     </p>
900    
901     <p>
902     Each individual chapter should have its own date and version elements. The
903     latest date of all chapters and master document will be displayed when a user
904     browses through all parts of the book.
905     </p>
906    
907     </body>
908     </section>
909 swift 1.17 </chapter>
910    
911     <chapter>
912 neysx 1.67 <title>Advanced Handbook Features</title>
913     <section>
914     <title>Global Values</title>
915     <body>
916    
917     <p>
918     Sometimes, the same values are repeated many times in several parts of a
919     handbook. Global search and replace operations tend to forget some or introduce
920     unwanted changes. Besides, it can be useful to define different values to be
921     used in shared chapters depending on which handbook includes the chapter.
922     </p>
923    
924     <p>
925     Global values can be defined in a handbook master file and used in all included
926     chapters.
927     </p>
928    
929     <p>
930     To define global values, add a <c>&lt;values&gt;</c> element to the handbook
931     master file. Each value is then defined in a <c>&lt;key&gt;</c> element whose
932     <c>id</c> attribute identifies the value, i.e. it is the name of your variable.
933     The content of the <c>&lt;key&gt;</c> is its value.
934     </p>
935    
936     <p>
937     The following example defines three values in a handbook master file:
938     </p>
939    
940     <pre caption="Define values in a handbook">
941     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
942     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
943     &lt;!-- &#36;Header&#36; --&gt;
944    
945     &lt;book&gt;
946     &lt;title&gt;Example Book Usage&lt;/title&gt;
947    
948     <i>&lt;values>
949     &lt;key id="arch"&gt;x86&lt;/key&gt;
950     &lt;key id="min-cd-name"&gt;install-x86-minimal-2007.0-r1.iso&lt;/key&gt;
951     &lt;key id="min-cd-size"&gt;57&lt;/key&gt;
952     &lt;/values&gt;</i>
953    
954     &lt;author...&gt;
955     ...
956     &lt;/author&gt;
957    
958     ...
959     </pre>
960    
961     <p>
962     The defined values can then be used throughout the handbook with the in-line
963     <c>&lt;keyval id="key_id"/&gt;</c> element. Specify the name of the key in its
964     <c>id</c> attribute, e.g. &lt;keyval id="min-cd-name"/&gt; would be replaced by
965     "install-x86-minimal-2007.0-r1.iso" in our example.
966     </p>
967    
968     <pre caption="Using defined values">
969     &lt;p&gt;
970     The Minimal Installation CD is called &lt;c&gt;<i>&lt;keyval id="min-cd-name"/&gt;</i>&lt;/c&gt;
971     and takes up only <i>&lt;keyval id="min-cd-size"/&gt;</i> MB of diskspace. You can use this
972     Installation CD to install Gentoo, but &lt;e&gt;only&lt;/e&gt; with a working Internet
973     connection.
974     &lt;/p&gt;
975     </pre>
976    
977     <p>
978     To make life easier on our translators, only use actual values, i.e. content
979     that does not need to be translated. For instance, we defined the
980     <c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>.
981     </p>
982    
983     </body>
984     </section>
985     <section>
986     <title>Conditional Elements</title>
987     <body>
988    
989     <p>
990     Chapters that are shared by several handbooks such as our <uri
991     link="/doc/en/handbook/">Installation Handbooks</uri> often have small
992     differences depending on which handbook includes them. Instead of adding
993     content that is irrelevant to some handbooks, authors can add a condition to
994     the following elements: <c>&lt;section&gt;</c>, <c>&lt;subsection&gt;</c>,
995     <c>&lt;body&gt;</c>, <c>&lt;note&gt;</c>, <c>&lt;impo&gt;</c>,
996     <c>&lt;warn&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;p&gt;</c>,
997     <c>&lt;table&gt;</c>, <c>&lt;tr&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>
998     and <c>&lt;li&gt;</c>.
999     </p>
1000    
1001     <p>
1002     The condition must be an <uri
1003     link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be
1004     evaluated when transforming the XML. If it evaluates to <c>true</c>, the
1005     element is processed, if not, it is ignored. The condition is specified in a
1006     <c>test</c> attribute.
1007     </p>
1008    
1009     <p>
1010     The following example uses the <c>arch</c> value that is defined in each
1011     handbook master file to condition some content:
1012     </p>
1013    
1014     <pre caption="Using conditional elements">
1015     &lt;body test="contains('AMD64 x86',func:keyval('arch'))"&gt;
1016    
1017     &lt;p&gt;
1018     This paragraph applies to both x86 and AMD64 architectures.
1019     &lt;/p&gt;
1020    
1021     &lt;p test="func:keyval('arch')='x86'"&gt;
1022     This paragraph only applies to the x86 architecture.
1023     &lt;/p&gt;
1024    
1025     &lt;p test="func:keyval('arch')='AMD64'"&gt;
1026     This paragraph only applies to the AMD64 architecture.
1027     &lt;/p&gt;
1028    
1029     &lt;p test="func:keyval('arch')='PPC'"&gt;
1030     This paragraph will never be seen!
1031     The whole body is skipped because of the first condition.
1032     &lt;/p&gt;
1033    
1034     &lt;/body&gt;
1035    
1036     &lt;body test="contains('AMD64 PPC64',func:keyval('arch'))"&gt;
1037    
1038     &lt;p&gt;
1039     This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because
1040     the 'AMD64 PPC64' string does contain 'PPC'.
1041     &lt;/p&gt;
1042    
1043     &lt;note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"&gt;
1044     This note only applies to the AMD64 and PPC64 architectures.
1045     &lt;/note&gt;
1046    
1047     &lt;/body&gt;
1048     </pre>
1049    
1050     </body>
1051     </section>
1052     </chapter>
1053    
1054     <chapter id="codingstyle">
1055 swift 1.17 <title>Coding Style</title>
1056     <section>
1057     <title>Introduction</title>
1058     <body>
1059    
1060     <p>
1061     Since all Gentoo Documentation is a joint effort and several people will
1062     most likely change existing documentation, a coding style is needed.
1063     A coding style contains two sections. The first one is regarding
1064 swift 1.45 internal coding - how the XML-tags are placed. The second one is
1065 swift 1.17 regarding the content - how not to confuse the reader.
1066     </p>
1067    
1068     <p>
1069     Both sections are described next.
1070     </p>
1071    
1072     </body>
1073     </section>
1074     <section>
1075     <title>Internal Coding Style</title>
1076     <body>
1077    
1078     <p>
1079     <b>Newlines</b> must be placed immediately after <e>every</e>
1080     GuideXML-tag (both opening as closing), except for:
1081     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
1082     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
1083     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
1084 swift 1.44 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
1085 neysx 1.37 <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
1086 swift 1.17 </p>
1087    
1088     <p>
1089     <b>Blank lines</b> must be placed immediately after <e>every</e>
1090     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
1091     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
1092 swift 1.18 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
1093     <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
1094     <c>&lt;impo&gt;</c> (opening tags only).
1095 swift 1.17 </p>
1096    
1097     <p>
1098     <b>Word-wrapping</b> must be applied at 80 characters except inside
1099 neysx 1.51 <c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
1100     choice (for instance when a URL exceeds the maximum amount of characters). The
1101     editor must then wrap whenever the first whitespace occurs. You should try to
1102     keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
1103     columns to help console users.
1104 swift 1.17 </p>
1105    
1106     <p>
1107 neysx 1.51 <b>Indentation</b> may not be used, except with the XML-constructs of which the
1108     parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
1109 neysx 1.53 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>, <c>&lt;dl&gt;</c>, and
1110     <c>&lt;author&gt;</c>. If indentation is used, it <e>must</e> be two spaces for
1111     each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
1112     Besides, tabs are not allowed in GuideXML documents.
1113 swift 1.17 </p>
1114    
1115     <p>
1116 neysx 1.53 In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>,
1117 neysx 1.57 <c>&lt;li&gt;</c> or <c>&lt;dd&gt;</c> constructs, indentation must be used for
1118 neysx 1.53 the content.
1119 swift 1.17 </p>
1120    
1121     <p>
1122     An example for indentation is:
1123     </p>
1124    
1125 neysx 1.37 <pre caption="Indentation Example">
1126 swift 1.17 &lt;table&gt;
1127     &lt;tr&gt;
1128     &lt;th&gt;Foo&lt;/th&gt;
1129     &lt;th&gt;Bar&lt;/th&gt;
1130     &lt;/tr&gt;
1131     &lt;tr&gt;
1132 swift 1.48 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
1133 swift 1.17 &lt;ti&gt;
1134     In case text cannot be shown within an 80-character wide line, you
1135 swift 1.48 must use indentation if the parent tag allows it
1136 swift 1.17 &lt;/ti&gt;
1137     &lt;/tr&gt;
1138     &lt;/table&gt;
1139    
1140     &lt;ul&gt;
1141     &lt;li&gt;First option&lt;/li&gt;
1142     &lt;li&gt;Second option&lt;/li&gt;
1143     &lt;/ul&gt;
1144     </pre>
1145    
1146     <p>
1147 neysx 1.53 <b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
1148     and the attribute value. As an example:
1149 swift 1.17 </p>
1150    
1151     <pre caption="Attributes">
1152     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
1153     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
1154     </pre>
1155    
1156     </body>
1157     </section>
1158     <section>
1159     <title>External Coding Style</title>
1160     <body>
1161    
1162     <p>
1163 neysx 1.53 Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c>,
1164     <c>&lt;ol&gt;</c>) and <c>&lt;dl&gt;</c>, periods (".") should not be used
1165     unless multiple sentences are used. In that case, every sentence should end
1166     with a period (or other reading marks).
1167 swift 1.17 </p>
1168    
1169     <p>
1170     Every sentence, including those inside tables and listings, should start
1171     with a capital letter.
1172     </p>
1173    
1174     <pre caption="Periods and capital letters">
1175     &lt;ul&gt;
1176     &lt;li&gt;No period&lt;/li&gt;
1177     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
1178     &lt;/ul&gt;
1179     </pre>
1180    
1181     <p>
1182     Code Listings should <e>always</e> have a <c>caption</c>.
1183     </p>
1184    
1185     <p>
1186     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
1187 neysx 1.35 possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
1188     Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
1189 swift 1.15 </p>
1190 swift 1.18
1191     <p>
1192 neysx 1.37 When you comment something inside a <c>&lt;pre&gt;</c> construct, use
1193     <c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
1194     that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
1195     for C code, etc.) Also place the comment <e>before</e> the subject of the
1196     comment.
1197 swift 1.18 </p>
1198    
1199     <pre caption="Comment example">
1200     <comment>(Substitute "john" with your user name)</comment>
1201     # <i>id john</i>
1202     </pre>
1203 drobbins 1.1
1204     </body>
1205     </section>
1206     </chapter>
1207 swift 1.15
1208 drobbins 1.1 <chapter>
1209     <title>Resources</title>
1210     <section>
1211 swift 1.15 <title>Start writing</title>
1212     <body>
1213    
1214     <p>
1215 neysx 1.67 GuideXML has been specially designed to be "lean and mean" so that developers
1216     can spend more time writing documentation and less time learning the actual XML
1217 swift 1.15 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
1218 neysx 1.67 to start writing quality Gentoo documentation. You might be interested in our
1219     <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips
1220     &amp; Tricks</uri>. If you'd like to help (or have any questions about
1221     GuideXML), please post a message to the <uri
1222     link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like
1223     to tackle. Have fun!
1224 swift 1.15 </p>
1225    
1226     </body>
1227 drobbins 1.1 </section>
1228     </chapter>
1229     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20