/[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.72 - (hide annotations) (download) (as text)
Sun Oct 7 08:19:42 2012 UTC (21 months, 2 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.71: +4 -12 lines
File MIME type: application/xml
Bug #379883 - Remove reference to @link

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

  ViewVC Help
Powered by ViewVC 1.1.20