/[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.34 - (hide annotations) (download) (as text)
Tue Oct 19 15:23:16 2004 UTC (10 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.33: +5 -5 lines
File MIME type: application/xml
#68142 fixed link to proj/en/gdp/doc/doc-tipsntricks.xml (was still pointing to /doc/)

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

  ViewVC Help
Powered by ViewVC 1.1.20