/[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.49 - (hide annotations) (download) (as text)
Tue Aug 23 09:18:12 2005 UTC (8 years, 11 months ago) by neysx
Branch: MAIN
Changes since 1.48: +7 -6 lines
File MIME type: application/xml
#103418 Added missing blank line. Also bumped license to 2.5

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

  ViewVC Help
Powered by ViewVC 1.1.20