/[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.23 - (hide annotations) (download) (as text)
Mon Nov 17 17:05:58 2003 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.22: +19 -3 lines
File MIME type: application/xml
Add information about the id attribute

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.23 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.22 2003/11/15 00:32:59 neysx Exp $ -->
3 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 zhen 1.2 <guide link="/doc/en/xml-guide.xml">
6 zhen 1.9 <title>Gentoo Linux XML Guide</title>
7 swift 1.15
8     <author title="Author">
9     <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10     </author>
11 swift 1.19 <author title="Author"><!-- zhen@gentoo.org -->
12     John P. Davis
13 swift 1.15 </author>
14     <author title="Editor">
15     <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16     </author>
17 drobbins 1.1
18 swift 1.13 <license/>
19 swift 1.15 <abstract>
20     This guide shows you how to compose web documentation using the new lightweight
21     Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
22     documentation, and this document itself was created using GuideXML. This guide
23     assumes a basic working knowledge of XML and HTML.
24 drobbins 1.1 </abstract>
25    
26 swift 1.23 <version>2.5</version>
27     <date>November 17, 2003</date>
28 drobbins 1.1
29     <chapter>
30     <title>Guide basics</title>
31     <section>
32     <title>Guide XML design goals</title>
33     <body>
34    
35 swift 1.15 <p>
36     The guide XML syntax is lightweight yet expressive, so that it is easy to
37 drobbins 1.1 learn yet also provides all the features we need for the creation of web
38     documentation. The number of tags is kept to a minimum -- just those we need.
39     This makes it easy to transform guide into other formats, such as DocBook
40 swift 1.15 XML/SGML or web-ready HTML.
41     </p>
42 drobbins 1.1
43 swift 1.15 <p>
44     The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45     documents.
46     </p>
47 drobbins 1.1
48     </body>
49     </section>
50     <section>
51 swift 1.20 <title>Further Resources</title>
52 drobbins 1.1 <body>
53    
54 swift 1.15 <p>
55 swift 1.20 If you are planning on contributing documentation to Gentoo, or you want to test
56     GuideXML, please read the <uri
57     link="http://www.gentoo.org/proj/en/gdp/doc/en/docdev.xml">Documentation
58     Developer Guide</uri> which contains tips and tricks for documentation
59     development.
60 drobbins 1.1 </p>
61    
62     </body>
63     </section>
64     </chapter>
65 swift 1.15
66 drobbins 1.1 <chapter>
67 swift 1.15 <title>Guide XML</title>
68 drobbins 1.1 <section>
69     <title>Basic structure</title>
70     <body>
71    
72 swift 1.15 <p>
73     Now that you know how to transform guide XML, you're ready to start learning
74     the GuideXML syntax. We'll start with the the initial tags used in a guide
75     XML document:
76     </p>
77 drobbins 1.1
78     <pre caption="The initial part of a guide XML document">
79 zhen 1.6 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
80     &lt;guide link="relative_link_to_your_guide"&gt;
81 drobbins 1.1 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
82 swift 1.15 &lt;author title="<i>Chief Architect</i>"&gt;
83     &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt;
84 drobbins 1.1 &lt;/author&gt;
85 swift 1.15 &lt;author title="<i>Editor</i>"&gt;
86     &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt;
87 drobbins 1.1 &lt;/author&gt;
88    
89 swift 1.15 &lt;abstract&gt;
90     <i>This guide shows you how to compose web documentation using
91     our new lightweight Gentoo GuideXML syntax. This syntax is the official
92 drobbins 1.1 format for Gentoo Linux web documentation, and this document itself was created
93 swift 1.15 using GuideXML.</i>
94     &lt;/abstract&gt;
95 drobbins 1.1
96 swift 1.14 &lt;license/&gt;
97    
98 drobbins 1.1 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
99     &lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
100     </pre>
101    
102 swift 1.15 <p>
103     On the first, line, we see the requisite tag that identifies this as an XML
104 drobbins 1.1 document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
105     guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
106     Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
107 swift 1.15 guide document.
108     </p>
109 drobbins 1.1
110 swift 1.15 <p>
111     Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
112 drobbins 1.1 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
113     allows for an optional <c>title=</c> element, used to specify the author's
114     relationship to the document (author, co-author, editor, etc.). In this
115     particular example, the authors' names are enclosed in another tag -- a
116     <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
117     person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
118     more than one <c>&lt;author&gt;</c> element is required per guide document.
119     </p>
120    
121 swift 1.15 <p>
122     Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
123 drobbins 1.1 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
124     current version number, and the current version date (in DD MMM YYYY format)
125     respectively. This rounds out the tags that should appear at the beginning of
126     a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
127     tags, these tags shouldn't appear anywhere else except immediately inside the
128     <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
129 swift 1.15 required) that these tags appear before the content of the document.
130     </p>
131 swift 1.14
132 swift 1.15 <p>
133     Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
134 swift 1.14 document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
135     Commons - Attribution / Share Alike</uri> license as required by the <uri
136     link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
137 swift 1.15 </p>
138 drobbins 1.1
139     </body>
140     </section>
141     <section>
142     <title>Chapters and sections</title>
143     <body>
144 swift 1.15
145     <p>
146     Once the initial tags have been specified, you're ready to start adding
147 drobbins 1.1 the structural elements of the document. Guide documents are divided into
148     chapters, and each chapter can hold one or more sections. Every chapter
149     and section has a title. Here's an example chapter with a single section,
150 neysx 1.16 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
151 drobbins 1.1 excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
152     (if minimal) guide document:
153     </p>
154    
155     <pre>
156     &lt;chapter&gt;
157     &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
158     &lt;section&gt;
159 swift 1.15 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
160     &lt;body&gt;
161    
162     &lt;p&gt;
163     <i>This is the actual text content of my section.</i>
164     &lt;/p&gt;
165    
166     &lt;/body&gt;
167 drobbins 1.1 &lt;/section&gt;
168     &lt;/chapter&gt;
169     </pre>
170    
171 swift 1.15 <p>
172     Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
173 drobbins 1.1 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
174     adding a <c>&lt;section&gt;</c> element. If you look inside the
175     <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
176     <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
177     is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
178     content of this particular section. We'll look at the tags that are allowed
179 swift 1.15 inside a <c>&lt;body&gt;</c> element in a bit.
180     </p>
181 drobbins 1.1
182 swift 1.15 <note>
183     A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
184     elements, and a <c>&lt;chapter&gt;</c> can contain multiple
185     <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
186     element can only contain one <c>&lt;body&gt;</c> element.
187     </note>
188 drobbins 1.1
189     </body>
190     </section>
191     <section>
192     <title>An example &lt;body&gt;</title>
193     <body>
194 swift 1.15
195 drobbins 1.1 <p>
196     Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c>&lt;body&gt;</c> element:
197     </p>
198 swift 1.15
199 drobbins 1.1 <pre>
200     &lt;p&gt;
201     This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
202     &lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
203     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.
204     &lt;/p&gt;
205    
206     &lt;pre&gt;
207     This is text output or code.
208     # &lt;i&gt;this is user input&lt;/i&gt;
209    
210     Make HTML/XML easier to read by using selective emphasis:
211     &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
212    
213     &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
214     &lt;/pre&gt;
215 swift 1.15
216     &lt;note&gt;
217     This is a note.
218     &lt;/note&gt;
219    
220     &lt;warn&gt;
221     This is a warning.
222     &lt;/warn&gt;
223    
224     &lt;impo&gt;
225     This is important.
226     &lt;/impo&gt;
227 drobbins 1.1 </pre>
228 swift 1.15
229     <p>
230     Now, here's how this <c>&lt;body&gt;</c> element is rendered:
231     </p>
232 drobbins 1.1
233     <p>
234     This is a paragraph. <path>/etc/passwd</path> is a file.
235     <uri>http://www.gentoo.org</uri> is my favorite website.
236     Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
237     </p>
238    
239     <pre>
240     This is text output or code.
241     # <i>this is user input</i>
242    
243     Make HTML/XML easier to read by using selective emphasis:
244     &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
245    
246     <codenote>This is how to insert an inline note into the code block</codenote>
247     </pre>
248 swift 1.15
249     <note>
250     This is a note.
251     </note>
252    
253     <warn>
254     This is a warning.
255     </warn>
256    
257     <impo>
258     This is important.
259     </impo>
260    
261 drobbins 1.1 </body>
262     </section>
263     <section>
264     <title>The &lt;body&gt; tags</title>
265     <body>
266    
267 swift 1.15 <p>
268     We introduced a lot of new tags in the previous section -- here's what you
269 drobbins 1.1 need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
270     block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
271     <c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
272     Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
273     these are the only tags that should appear immediately inside a
274     <c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
275     stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
276     <c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
277 swift 1.12 preserves its whitespace exactly, making it well-suited for code excerpts.
278 swift 1.15 You can also name the <c>&lt;pre&gt;</c> tag:
279     </p>
280 swift 1.12
281     <pre caption = "Named &lt;pre&gt;">
282     &lt;pre caption = "Output of uptime"&gt;
283     # &lt;i&gt;uptime&lt;/i&gt;
284     16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
285     &lt;/pre&gt;
286     </pre>
287 drobbins 1.1
288     </body>
289     </section>
290     <section>
291     <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
292     <body>
293    
294 swift 1.15 <p>
295     The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
296 drobbins 1.1 be used inside any child <c>&lt;body&gt;</c> tag, except for
297 swift 1.15 <c>&lt;pre&gt;</c>.
298     </p>
299 drobbins 1.1
300 swift 1.15 <p>
301     The <c>&lt;path&gt;</c> element is used to mark text that refers to an
302     <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
303     <e>simple filename</e>. This element is generally rendered with a monospaced
304     font to offset it from the standard paragraph type.
305     </p>
306 drobbins 1.1
307 swift 1.15 <p>
308     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
309 drobbins 1.1 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
310     that they can type in that will perform some kind of action. For example, all
311     the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
312     element because they represent something that the user could type in that is
313     not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
314     quickly identify commands that they need to type in. Also, because
315     <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
316     necessary to surround user input with double-quotes</e>. For example, don't
317     refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
318 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
319     adorable!
320     </p>
321 drobbins 1.1
322 swift 1.15 <p>
323     <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
324 drobbins 1.1 I <e>really</e> should use semicolons more often. As you can see, this text is
325     offset from the regular paragraph type for emphasis. This helps to give your
326 swift 1.15 prose more <e>punch</e>!
327     </p>
328 drobbins 1.1
329     </body>
330     </section>
331     <section>
332     <title>&lt;mail&gt; and &lt;uri&gt;</title>
333     <body>
334    
335 swift 1.15 <p>
336     We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
337     some text with a particular email address, and takes the form <c>&lt;mail
338     link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
339     </p>
340 drobbins 1.1
341 swift 1.15 <p>
342     The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
343 drobbins 1.1 Internet. It has two forms -- the first can be used when you want to have the
344     actual URI displayed in the body text, such as this link to
345     <uri>http://www.gentoo.org</uri>. To create this link, I typed
346     <c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
347     when you want to associate a URI with some other text -- for example, <uri
348 swift 1.15 link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
349     <e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the
350     Gentoo Linux website&lt;/uri&gt;</c>.
351 drobbins 1.1 </p>
352    
353     </body>
354     </section>
355     <section>
356     <title>Figures</title>
357    
358     <body>
359    
360 swift 1.15 <p>
361     Here's how to insert a figure into a document -- <c>&lt;figure
362 drobbins 1.1 link="mygfx.png" short="my picture" caption="my favorite picture of all
363     time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
364     the <c>short=</c> attribute specifies a short description (currently used for
365     the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
366     :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
367 swift 1.15 for adding images without captions, borders, etc.
368     </p>
369 drobbins 1.1
370     </body>
371     </section>
372     <section>
373     <title>Tables and lists</title>
374     <body>
375    
376 swift 1.15 <p>
377     Guide supports a simplified table syntax similar to that of HTML. To start
378 drobbins 1.1 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
379     tag. However, for inserting actual table data, we <e>don't</e> support the
380     HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
381     header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
382 swift 1.15 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
383     -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
384 drobbins 1.1 first row. Currently, these tags don't support any attributes, but some will
385     be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
386     </p>
387    
388 swift 1.15 <p>
389     To create ordered or unordered lists, simply use the HTML-style
390 drobbins 1.1 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
391     should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
392 swift 1.15 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
393     </p>
394 drobbins 1.1
395     </body>
396     </section>
397     <section>
398     <title>Intra-document references</title>
399     <body>
400    
401 swift 1.15 <p>
402     Guide makes it really easy to reference other parts of the document using
403 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
404     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
405     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
406     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
407     Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
408 swift 1.15 link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
409     link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
410     link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
411     adding other auto-link abilities (such as table support) soon.
412 swift 1.17 </p>
413 swift 1.23
414     <p>
415     However, some guides change often and using such "counting" can lead to broken
416     links. In order to cope with this, you can define a name for a
417     <c>&lt;chapter&gt;</c> or <c>&lt;section&gt;</c> by using the <c>id</c>
418     attribute, and then point to that attribute, like this:
419     </p>
420    
421     <pre caption="Using the id attribute">
422     &lt;chapter id="foo"&gt;
423     &lt;title&gt;This is foo!&lt;/title&gt;
424     ...
425     &lt;p&gt;
426     More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
427     &lt;/p&gt;
428     </pre>
429 swift 1.17
430     </body>
431     </section>
432     </chapter>
433    
434     <chapter>
435     <title>Coding Style</title>
436     <section>
437     <title>Introduction</title>
438     <body>
439    
440     <p>
441     Since all Gentoo Documentation is a joint effort and several people will
442     most likely change existing documentation, a coding style is needed.
443     A coding style contains two sections. The first one is regarding
444     internal coding - how the xml-tags are placed. The second one is
445     regarding the content - how not to confuse the reader.
446     </p>
447    
448     <p>
449     Both sections are described next.
450     </p>
451    
452     </body>
453     </section>
454     <section>
455     <title>Internal Coding Style</title>
456     <body>
457    
458     <p>
459     <b>Newlines</b> must be placed immediately after <e>every</e>
460     GuideXML-tag (both opening as closing), except for:
461     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
462     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
463     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
464     <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
465     <c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
466     </p>
467    
468     <p>
469     <b>Blank lines</b> must be placed immediately after <e>every</e>
470     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
471     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
472 swift 1.18 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
473     <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
474     <c>&lt;impo&gt;</c> (opening tags only).
475 swift 1.17 </p>
476    
477     <p>
478     <b>Word-wrapping</b> must be applied at 80 characters except inside
479     <c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
480     this rule (for instance when a URL exceeds the maximum amount of characters).
481     The editor must then wrap whenever the first whitespace occurs.
482     </p>
483    
484     <p>
485     <b>Indentation</b> may not be used, except with the XML-constructs of which
486     the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
487 swift 1.21 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation
488     is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
489     tabs and <e>not</e> more spaces.
490 swift 1.17 </p>
491    
492     <p>
493     In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
494     <c>&lt;li&gt;</c> constructs, indentation must be used for the content.
495     </p>
496    
497     <p>
498     An example for indentation is:
499     </p>
500    
501     <pre caption = "Indentation Example">
502     &lt;table&gt;
503     &lt;tr&gt;
504     &lt;th&gt;Foo&lt;/th&gt;
505     &lt;th&gt;Bar&lt;/th&gt;
506     &lt;/tr&gt;
507     &lt;tr&gt;
508     &lt;ti&gt;This is an example for indentation.&lt;/ti&gt;
509     &lt;ti&gt;
510     In case text cannot be shown within an 80-character wide line, you
511     must use indentation if the parent tag allows it.
512     &lt;/ti&gt;
513     &lt;/tr&gt;
514     &lt;/table&gt;
515    
516     &lt;ul&gt;
517     &lt;li&gt;First option&lt;/li&gt;
518     &lt;li&gt;Second option&lt;/li&gt;
519     &lt;/ul&gt;
520     </pre>
521    
522     <p>
523     <b>Attributes</b> may not have spaces in between the attribute, the
524     &quot;=&quot; mark, and the attribute value. As an example:
525     </p>
526    
527     <pre caption="Attributes">
528     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
529     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
530     </pre>
531    
532     </body>
533     </section>
534     <section>
535     <title>External Coding Style</title>
536     <body>
537    
538     <p>
539     Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
540     <c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
541     sentences are used. In that case, every sentence should end with a period (or
542     other reading marks).
543     </p>
544    
545     <p>
546     Every sentence, including those inside tables and listings, should start
547     with a capital letter.
548     </p>
549    
550     <pre caption="Periods and capital letters">
551     &lt;ul&gt;
552     &lt;li&gt;No period&lt;/li&gt;
553     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
554     &lt;/ul&gt;
555     </pre>
556    
557     <p>
558     Code Listings should <e>always</e> have a <c>caption</c>.
559     </p>
560    
561     <p>
562     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
563     possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
564     Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
565 swift 1.15 </p>
566 swift 1.18
567     <p>
568     When you comment something inside a <c>&lt;pre&gt;</c> construct, only use
569     <c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise,
570     use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e>
571     the subject of the comment.
572     </p>
573    
574     <pre caption="Comment example">
575     <comment>(Substitute "john" with your user name)</comment>
576     # <i>id john</i>
577     </pre>
578 drobbins 1.1
579     </body>
580     </section>
581     </chapter>
582 swift 1.15
583 drobbins 1.1 <chapter>
584     <title>Resources</title>
585     <section>
586 swift 1.15 <title>Start writing</title>
587     <body>
588    
589     <p>
590     Guide has been specially designed to be "lean and mean" so that developers
591     can spend more time writing documentation and less time learning the actual XML
592     syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
593     to start writing quality Gentoo Linux documentation. If you'd like to help (or
594     have any questions about guide), please post a message to the <mail
595     link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
596     like to tackle. Have fun!
597     </p>
598    
599     </body>
600 drobbins 1.1 </section>
601     </chapter>
602     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20