/[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.42 - (show annotations) (download) (as text)
Thu May 12 16:48:46 2005 UTC (9 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.41: +19 -13 lines
File MIME type: application/xml
Added info about $Header$ line

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

  ViewVC Help
Powered by ViewVC 1.1.20