/[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.35 - (hide annotations) (download) (as text)
Fri Dec 24 11:52:37 2004 UTC (9 years, 9 months ago) by neysx
Branch: MAIN
Changes since 1.34: +62 -28 lines
File MIME type: application/xml
Added date format (YYYY-MM-DD), date/version in HB individual chapters
Edited bits about linking to other parts of www.g.o and link/lang attributes

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

  ViewVC Help
Powered by ViewVC 1.1.20