/[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.33 - (show annotations) (download) (as text)
Fri Sep 24 20:46:42 2004 UTC (9 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.32: +3 -6 lines
File MIME type: application/xml
Daniel is no longer Chief Architect

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

  ViewVC Help
Powered by ViewVC 1.1.20