/[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.42 - (hide annotations) (download) (as text)
Thu May 12 16:48:46 2005 UTC (9 years, 3 months ago) by neysx
Branch: MAIN
Changes since 1.41: +19 -13 lines
File MIME type: application/xml
Added info about $Header$ line

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

  ViewVC Help
Powered by ViewVC 1.1.20