/[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.31 - (show annotations) (download) (as text)
Fri May 21 13:32:28 2004 UTC (10 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.30: +3 -1 lines
File MIME type: application/xml
Add internal link to license

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

  ViewVC Help
Powered by ViewVC 1.1.20