/[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.31 - (hide annotations) (download) (as text)
Fri May 21 13:32:28 2004 UTC (10 years, 1 month ago) by swift
Branch: MAIN
Changes since 1.30: +3 -1 lines
File MIME type: application/xml
Add internal link to license

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

  ViewVC Help
Powered by ViewVC 1.1.20