/[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.36 - (show annotations) (download) (as text)
Mon Feb 14 16:14:46 2005 UTC (9 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.35: +5 -6 lines
File MIME type: application/xml
#80909 - Remove reference to old, removed part of the document

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

  ViewVC Help
Powered by ViewVC 1.1.20