/[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.20 - (hide annotations) (download) (as text)
Fri Oct 31 14:48:15 2003 UTC (11 years ago) by swift
Branch: MAIN
Changes since 1.19: +8 -60 lines
File MIME type: application/xml
Fix #31872: reference docdev and use xml-guide only for guidexml stuff

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

  ViewVC Help
Powered by ViewVC 1.1.20