/[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.39 - (hide annotations) (download) (as text)
Sat Apr 16 19:45:35 2005 UTC (9 years ago) by swift
Branch: MAIN
Changes since 1.38: +6 -5 lines
File MIME type: application/xml
#89317 - Say that li/lo needs to be closed like XML requires

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

  ViewVC Help
Powered by ViewVC 1.1.20