/[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.26 - (hide annotations) (download) (as text)
Thu Feb 19 14:48:06 2004 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.25: +3 -3 lines
File MIME type: application/xml
Make DTD valid - No content change

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

  ViewVC Help
Powered by ViewVC 1.1.20