/[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.48 - (hide annotations) (download) (as text)
Thu Aug 11 11:01:06 2005 UTC (8 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.47: +5 -5 lines
File MIME type: application/xml
Hmmm... adhere to Coding Style in the section about Coding Style :)

1 cam 1.41 <?xml version="1.0" encoding="UTF-8"?>
2 swift 1.48 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.47 2005/07/26 11:51:06 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.46 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33 swift 1.26 <license/>
34    
35 swift 1.48 <version>2.24</version>
36     <date>2005-08-11</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.43 &lt;guide link="<i>/doc/en/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.46 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&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 neysx 1.43 Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
116     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 absolute path to the
118     document relatively to the document root even though the file name alone will
119     work. It is mainly used to generate a link to a printer-friendly version of
120     your document. If you use a wrong value, the link to the printable version
121     will either not work or point to a wrong document. The <c>lang</c> attribute
122     can be used to specify the language code of your document. It is used to format
123     the date and insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the
124     specified language. The default 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 swift 1.45 <uri>http://forums.gentoo.org</uri> is my favorite web site.
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 swift 1.44 <title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title>
321 drobbins 1.1 <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.44 <c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
327     <c>&lt;pre&gt;</c>.
328 swift 1.15 </p>
329 drobbins 1.1
330 swift 1.15 <p>
331     The <c>&lt;path&gt;</c> element is used to mark text that refers to an
332     <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
333 swift 1.45 <e>simple filename</e>. This element is generally rendered with a mono spaced
334 swift 1.15 font to offset it from the standard paragraph type.
335     </p>
336 drobbins 1.1
337 swift 1.15 <p>
338     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
339 drobbins 1.1 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
340     that they can type in that will perform some kind of action. For example, all
341     the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
342     element because they represent something that the user could type in that is
343     not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
344     quickly identify commands that they need to type in. Also, because
345     <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
346     necessary to surround user input with double-quotes</e>. For example, don't
347     refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
348 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
349     adorable!
350     </p>
351 drobbins 1.1
352 swift 1.15 <p>
353 swift 1.44 When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>,
354     use <c>&lt;i&gt;</c> instead.
355     </p>
356    
357     <p>
358 swift 1.15 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
359 drobbins 1.1 I <e>really</e> should use semicolons more often. As you can see, this text is
360     offset from the regular paragraph type for emphasis. This helps to give your
361 swift 1.15 prose more <e>punch</e>!
362     </p>
363 drobbins 1.1
364     </body>
365     </section>
366     <section>
367     <title>&lt;mail&gt; and &lt;uri&gt;</title>
368     <body>
369    
370 swift 1.15 <p>
371     We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
372     some text with a particular email address, and takes the form <c>&lt;mail
373     link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
374     </p>
375 drobbins 1.1
376 swift 1.15 <p>
377 neysx 1.35 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
378     It has two forms -- the first can be used when you want to have the actual URI
379     displayed in the body text, such as this link to
380     <uri>http://forums.gentoo.org</uri>. To create this link, I typed
381     <c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
382 drobbins 1.1 when you want to associate a URI with some other text -- for example, <uri
383 neysx 1.35 link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
384     link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
385     Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
386 swift 1.45 to link to other parts of the Gentoo web site. For instance, a link to the <uri
387 neysx 1.35 link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
388     link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
389     even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
390     link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
391 drobbins 1.1 </p>
392    
393     </body>
394     </section>
395     <section>
396     <title>Figures</title>
397     <body>
398    
399 swift 1.15 <p>
400     Here's how to insert a figure into a document -- <c>&lt;figure
401 drobbins 1.1 link="mygfx.png" short="my picture" caption="my favorite picture of all
402     time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
403     the <c>short=</c> attribute specifies a short description (currently used for
404     the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
405     :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
406 swift 1.15 for adding images without captions, borders, etc.
407     </p>
408 drobbins 1.1
409     </body>
410     </section>
411     <section>
412     <title>Tables and lists</title>
413     <body>
414    
415 swift 1.15 <p>
416     Guide supports a simplified table syntax similar to that of HTML. To start
417 drobbins 1.1 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
418     tag. However, for inserting actual table data, we <e>don't</e> support the
419     HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
420     header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
421 swift 1.15 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
422     -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
423 neysx 1.47 first row. Currently, these tags don't support any attributes, but some might
424     be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) later.
425 drobbins 1.1 </p>
426    
427 swift 1.15 <p>
428 swift 1.39 To create ordered or unordered lists, simply use the XHTML-style
429 drobbins 1.1 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
430 swift 1.30 should only appear inside a <c>&lt;body&gt;</c>, <c>&lt;ul&gt;</c> or
431 swift 1.39 <c>&lt;ol&gt;</c> tag. You need to close the tags as well (which is a general
432     XML requirement).
433 swift 1.15 </p>
434 drobbins 1.1
435     </body>
436     </section>
437     <section>
438     <title>Intra-document references</title>
439     <body>
440    
441 swift 1.15 <p>
442     Guide makes it really easy to reference other parts of the document using
443 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
444     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
445     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
446     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
447     Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
448 swift 1.40 link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
449 swift 1.15 link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
450 swift 1.40 link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
451 swift 1.15 adding other auto-link abilities (such as table support) soon.
452 swift 1.17 </p>
453 swift 1.23
454     <p>
455     However, some guides change often and using such "counting" can lead to broken
456     links. In order to cope with this, you can define a name for a
457 neysx 1.47 <c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
458     the <c>id</c> attribute, and then point to that attribute, like this:
459 swift 1.23 </p>
460    
461     <pre caption="Using the id attribute">
462     &lt;chapter id="foo"&gt;
463     &lt;title&gt;This is foo!&lt;/title&gt;
464     ...
465     &lt;p&gt;
466     More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
467     &lt;/p&gt;
468     </pre>
469 swift 1.17
470     </body>
471     </section>
472     </chapter>
473    
474     <chapter>
475     <title>Coding Style</title>
476     <section>
477     <title>Introduction</title>
478     <body>
479    
480     <p>
481     Since all Gentoo Documentation is a joint effort and several people will
482     most likely change existing documentation, a coding style is needed.
483     A coding style contains two sections. The first one is regarding
484 swift 1.45 internal coding - how the XML-tags are placed. The second one is
485 swift 1.17 regarding the content - how not to confuse the reader.
486     </p>
487    
488     <p>
489     Both sections are described next.
490     </p>
491    
492     </body>
493     </section>
494     <section>
495     <title>Internal Coding Style</title>
496     <body>
497    
498     <p>
499     <b>Newlines</b> must be placed immediately after <e>every</e>
500     GuideXML-tag (both opening as closing), except for:
501     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
502     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
503     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
504 swift 1.44 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
505 neysx 1.37 <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
506 swift 1.17 </p>
507    
508     <p>
509     <b>Blank lines</b> must be placed immediately after <e>every</e>
510     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
511     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
512 swift 1.18 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
513     <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
514     <c>&lt;impo&gt;</c> (opening tags only).
515 swift 1.17 </p>
516    
517     <p>
518     <b>Word-wrapping</b> must be applied at 80 characters except inside
519     <c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
520     this rule (for instance when a URL exceeds the maximum amount of characters).
521     The editor must then wrap whenever the first whitespace occurs.
522     </p>
523    
524     <p>
525     <b>Indentation</b> may not be used, except with the XML-constructs of which
526     the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
527 swift 1.21 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation
528     is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
529     tabs and <e>not</e> more spaces.
530 swift 1.17 </p>
531    
532     <p>
533     In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
534     <c>&lt;li&gt;</c> constructs, indentation must be used for the content.
535     </p>
536    
537     <p>
538     An example for indentation is:
539     </p>
540    
541 neysx 1.37 <pre caption="Indentation Example">
542 swift 1.17 &lt;table&gt;
543     &lt;tr&gt;
544     &lt;th&gt;Foo&lt;/th&gt;
545     &lt;th&gt;Bar&lt;/th&gt;
546     &lt;/tr&gt;
547     &lt;tr&gt;
548 swift 1.48 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
549 swift 1.17 &lt;ti&gt;
550     In case text cannot be shown within an 80-character wide line, you
551 swift 1.48 must use indentation if the parent tag allows it
552 swift 1.17 &lt;/ti&gt;
553     &lt;/tr&gt;
554     &lt;/table&gt;
555    
556     &lt;ul&gt;
557     &lt;li&gt;First option&lt;/li&gt;
558     &lt;li&gt;Second option&lt;/li&gt;
559     &lt;/ul&gt;
560     </pre>
561    
562     <p>
563     <b>Attributes</b> may not have spaces in between the attribute, the
564     &quot;=&quot; mark, and the attribute value. As an example:
565     </p>
566    
567     <pre caption="Attributes">
568     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
569     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
570     </pre>
571    
572     </body>
573     </section>
574     <section>
575     <title>External Coding Style</title>
576     <body>
577    
578     <p>
579     Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
580     <c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
581     sentences are used. In that case, every sentence should end with a period (or
582     other reading marks).
583     </p>
584    
585     <p>
586     Every sentence, including those inside tables and listings, should start
587     with a capital letter.
588     </p>
589    
590     <pre caption="Periods and capital letters">
591     &lt;ul&gt;
592     &lt;li&gt;No period&lt;/li&gt;
593     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
594     &lt;/ul&gt;
595     </pre>
596    
597     <p>
598     Code Listings should <e>always</e> have a <c>caption</c>.
599     </p>
600    
601     <p>
602     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
603 neysx 1.35 possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
604     Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
605 swift 1.15 </p>
606 swift 1.18
607     <p>
608 neysx 1.37 When you comment something inside a <c>&lt;pre&gt;</c> construct, use
609     <c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
610     that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
611     for C code, etc.) Also place the comment <e>before</e> the subject of the
612     comment.
613 swift 1.18 </p>
614    
615     <pre caption="Comment example">
616     <comment>(Substitute "john" with your user name)</comment>
617     # <i>id john</i>
618     </pre>
619 drobbins 1.1
620     </body>
621     </section>
622     </chapter>
623 swift 1.15
624 drobbins 1.1 <chapter>
625 swift 1.25 <title>Handbook Format</title>
626     <section>
627     <title>Guide vs Book</title>
628     <body>
629    
630     <p>
631     For high-volume documentation, such as the <uri
632 neysx 1.29 link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
633 swift 1.25 broader format was needed. We designed a GuideXML-compatible enhancement that
634     allows us to write modular and multi-page documentation.
635     </p>
636    
637     </body>
638     </section>
639     <section>
640     <title>Main File</title>
641     <body>
642    
643     <p>
644     The first change is the need for a "master" document. This document contains no
645     real content, but links to the individual documentation modules. The syntaxis
646     doesn't differ much from GuideXML:
647     </p>
648    
649     <pre caption="Example book usage">
650     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
651     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
652 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
653 swift 1.25
654     &lt;<i>book</i> link="example.xml"&gt;
655     &lt;title&gt;Example Book Usage&lt;/title&gt;
656    
657     &lt;author...&gt;
658     ...
659     &lt;/author&gt;
660    
661     &lt;abstract&gt;
662     ...
663     &lt;/abstract&gt;
664    
665     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
666 swift 1.32 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
667 swift 1.25 &lt;license/&gt;
668    
669     &lt;version&gt;...&lt;/version&gt;
670     &lt;date&gt;...&lt;/date&gt;
671     </pre>
672    
673     <p>
674     So far no real differences (except for the <c>&lt;book&gt;</c> instead of
675     <c>&lt;guide&gt;</c> tag). Instead of starting with the individual
676     <c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the
677     equivalent of a separate part in a book:
678     </p>
679    
680     <pre caption="Defining a part">
681     &lt;part&gt;
682     &lt;title&gt;Part One&lt;/title&gt;
683     &lt;abstract&gt;
684     ...
685     &lt;/abstract&gt;
686    
687     <comment>(Defining the several chapters)</comment>
688     &lt;/part&gt;
689     </pre>
690    
691     <p>
692     Each part is accompanied by a <c>&lt;title&gt;</c> and an
693     <c>&lt;abstract&gt;</c> which gives a small introduction to the part.
694     </p>
695    
696     <p>
697     Inside each part, you define the individual <c>&lt;chapter&gt;</c>'s. Each
698     chapter <e>must</e> be a separate document. As a result it is no surprise that a
699     special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
700     document.
701     </p>
702    
703     <pre caption="Defining a chapter">
704     &lt;chapter&gt;
705     &lt;title&gt;Chapter One&lt;/title&gt;
706     &lt;abstract&gt;
707     This is a small explanation on chapter one.
708     &lt;/abstract&gt;
709    
710     &lt;include href="path/to/chapter-one.xml"/&gt;
711    
712     &lt;/chapter&gt;
713     </pre>
714    
715     </body>
716     </section>
717     <section>
718     <title>Designing the Individual Chapters</title>
719     <body>
720    
721     <p>
722     The content of an individual chapter is structured as follows:
723     </p>
724    
725     <pre caption="Chapter Syntax">
726     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
727     &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
728 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
729 swift 1.25
730     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
731 swift 1.32 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
732 swift 1.25
733     &lt;sections&gt;
734    
735 neysx 1.35 &lt;version&gt;...&lt;/version&gt;
736     &lt;date&gt;...&lt;/date&gt;
737    
738 swift 1.25 <comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
739    
740     &lt;/sections&gt;
741     </pre>
742    
743     <p>
744     Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
745     <c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
746     of <c>&lt;section&gt;</c> in a Guide).
747     </p>
748    
749 neysx 1.35 <p>
750     Each individual chapter should have its own date and version elements. The
751     latest date of all chapters and master document will be displayed when a user
752     browses through all parts of the book.
753     </p>
754    
755 swift 1.25 </body>
756     </section>
757     </chapter>
758    
759     <chapter>
760 drobbins 1.1 <title>Resources</title>
761     <section>
762 swift 1.15 <title>Start writing</title>
763     <body>
764    
765     <p>
766 neysx 1.35 Guide has been specially designed to be "lean and mean" so that developers can
767     spend more time writing documentation and less time learning the actual XML
768 swift 1.15 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
769 neysx 1.35 to start writing quality Gentoo Linux documentation. You might be interested
770     in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation
771     Development Tips &amp; Tricks</uri>. If you'd like to help (or have any
772     questions about guide), please post a message to the <mail
773     link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
774 swift 1.15 like to tackle. Have fun!
775     </p>
776    
777     </body>
778 drobbins 1.1 </section>
779     </chapter>
780     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20