/[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.36 - (hide annotations) (download) (as text)
Mon Feb 14 16:14:46 2005 UTC (9 years, 5 months ago) by swift
Branch: MAIN
Changes since 1.35: +5 -6 lines
File MIME type: application/xml
#80909 - Remove reference to old, removed part of the document

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

  ViewVC Help
Powered by ViewVC 1.1.20