/[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.51 - (show annotations) (download) (as text)
Sun Oct 9 11:00:20 2005 UTC (8 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.50: +85 -29 lines
File MIME type: application/xml
Documented disclaimers and some extra fixes

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

  ViewVC Help
Powered by ViewVC 1.1.20