/[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.30 - (hide annotations) (download) (as text)
Sun May 9 12:47:28 2004 UTC (10 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.29: +5 -5 lines
File MIME type: application/xml
Update xml guide to reflect new dtd

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

  ViewVC Help
Powered by ViewVC 1.1.20