/[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.66 - (show annotations) (download) (as text)
Wed Nov 29 15:48:57 2006 UTC (7 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.65: +3 -3 lines
File MIME type: application/xml
revert previous change

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.64 2006/05/11 17:07:41 rane 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="neysx@gentoo.org">Xavier Neys</mail>
10 </author>
11 <author title="Author">
12 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13 </author>
14 <author title="Author"><!-- zhen@gentoo.org -->
15 John P. Davis
16 </author>
17 <author title="Editor">
18 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
19 </author>
20 <author title="Editor">
21 <mail link="swift@gentoo.org">Sven Vermeulen</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>7</version>
36 <date>2006-05-11</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 our <uri
66 link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
67 which contains tips and tricks for documentation development.
68 </p>
69
70 <p>
71 You may want to look at the <uri link="?passthru=1">XML source</uri> of this
72 document while you read it.
73 </p>
74
75 </body>
76 </section>
77 </chapter>
78
79 <chapter>
80 <title>Guide XML</title>
81 <section>
82 <title>Basic structure</title>
83 <body>
84
85 <p>
86 Let's start learning the GuideXML syntax. We'll start with the the initial
87 tags used in a GuideXML document:
88 </p>
89
90 <pre caption="The initial part of a guide XML document">
91 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
92 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
93 &lt;!-- &#36;Header&#36; --&gt;
94
95 &lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt;
96 &lt;title&gt;<i>Gentoo Documentation Guide</i>&lt;/title&gt;
97
98 &lt;author title="<i>Author</i>"&gt;
99 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
100 &lt;/author&gt;
101
102 &lt;abstract&gt;
103 <i>This guide shows you how to compose web documentation using
104 our new lightweight Gentoo GuideXML syntax. This syntax is the official
105 format for Gentoo web documentation, and this document itself was created
106 using GuideXML.</i>
107 &lt;/abstract&gt;
108
109 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
110 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
111 &lt;license/&gt;
112
113 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
114 &lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
115 </pre>
116
117 <p>
118 On the first lines, we see the requisite tag that identifies this as an XML
119 document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
120 will be automatically modified by the CVS server and helps to track revisions.
121 Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
122 enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c>
123 attribute is compulsory and should preferably contain the absolute path to the
124 document relatively to the document root even though the file name alone will
125 work. It is mainly used to generate a link to a printer-friendly version of
126 your document. If you use a wrong value, the link to the printable version will
127 either not work or point to a wrong document. Translated documents <e>must</e>
128 specify the full path because it is also used to check whether a more recent
129 original document exists. The <c>lang</c> attribute should be used to specify
130 the language code of your document. It is used to format the date and insert
131 strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language.
132 The default is English.
133 </p>
134
135 <p>
136 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
137 guide document.
138 </p>
139
140 <p>
141 Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
142 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
143 allows for an optional <c>title</c> element, used to specify the author's
144 relationship to the document (author, co-author, editor, etc.). In this
145 particular example, the authors' names are enclosed in another tag -- a
146 <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
147 person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
148 more than one <c>&lt;author&gt;</c> element is required per guide document.
149 </p>
150
151 <p>
152 Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
153 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
154 current version number, and the current version date (in YYYY-MM-DD format)
155 respectively. Dates that are invalid or not in the YYYY-MM-DD format will
156 appear verbatim in the rendered document.
157 </p>
158
159 <p>
160 This rounds out the tags that should appear at the beginning of a guide
161 document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these
162 tags shouldn't appear anywhere else except immediately inside the
163 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
164 required) that these tags appear before the content of the document.
165 </p>
166
167 <p>
168 Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document
169 under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
170 Commons - Attribution / Share Alike</uri> license as required by the <uri
171 link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
172 </p>
173
174 </body>
175 </section>
176 <section>
177 <title>Chapters and sections</title>
178 <body>
179
180 <p>
181 Once the initial tags have been specified, you're ready to start adding the
182 structural elements of the document. Guide documents are divided into
183 chapters, and each chapter can hold one or more sections. Every chapter and
184 section has a title. Here's an example chapter with a single section,
185 consisting of a paragraph. If you append this XML to the XML in the <uri
186 link="#doc_chap2_pre1">previous excerpt</uri> and append a
187 <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid (if minimal)
188 guide document:
189 </p>
190
191 <pre caption="Minimal guide example">
192 &lt;chapter&gt;
193 &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
194 &lt;section&gt;
195 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
196 &lt;body&gt;
197
198 &lt;p&gt;
199 <i>This is the actual text content of my section.</i>
200 &lt;/p&gt;
201
202 &lt;/body&gt;
203 &lt;/section&gt;
204 &lt;/chapter&gt;
205 </pre>
206
207 <p>
208 Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
209 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
210 adding a <c>&lt;section&gt;</c> element. If you look inside the
211 <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
212 <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
213 is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
214 content of this particular section. We'll look at the tags that are allowed
215 inside a <c>&lt;body&gt;</c> element in a bit.
216 </p>
217
218 <note>
219 A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
220 elements, and a <c>&lt;chapter&gt;</c> can contain multiple
221 <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
222 element can only contain one <c>&lt;body&gt;</c> element.
223 </note>
224
225 </body>
226 </section>
227 <section>
228 <title>An example &lt;body&gt;</title>
229 <body>
230
231 <p>
232 Now, it's time to learn how to mark up actual content. Here's the XML code for
233 an example <c>&lt;body&gt;</c> element:
234 </p>
235
236 <pre caption="Example of a body element">
237 &lt;p&gt;
238 This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
239 &lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
240 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.
241 &lt;/p&gt;
242
243 &lt;pre caption="Code Sample"&gt;
244 This is text output or code.
245 # &lt;i&gt;this is user input&lt;/i&gt;
246
247 Make HTML/XML easier to read by using selective emphasis:
248 &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
249
250 &lt;comment&gt;(This is how to insert a comment into a code block)&lt;/comment&gt;
251 &lt;/pre&gt;
252
253 &lt;note&gt;
254 This is a note.
255 &lt;/note&gt;
256
257 &lt;warn&gt;
258 This is a warning.
259 &lt;/warn&gt;
260
261 &lt;impo&gt;
262 This is important.
263 &lt;/impo&gt;
264 </pre>
265
266 <p>
267 Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
268 </p>
269
270 <p>
271 This is a paragraph. <path>/etc/passwd</path> is a file.
272 <uri>http://forums.gentoo.org</uri> is my favorite web site.
273 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
274 </p>
275
276 <pre caption="Code Sample">
277 This is text output or code.
278 # <i>this is user input</i>
279
280 Make HTML/XML easier to read by using selective emphasis:
281 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
282
283 <comment>(This is how to insert a comment into a code block)</comment>
284 </pre>
285
286 <note>
287 This is a note.
288 </note>
289
290 <warn>
291 This is a warning.
292 </warn>
293
294 <impo>
295 This is important.
296 </impo>
297
298 </body>
299 </section>
300 <section>
301 <title>The &lt;body&gt; tags</title>
302 <body>
303
304 <p>
305 We introduced a lot of new tags in the previous section -- here's what you need
306 to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block),
307 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and <c>&lt;impo&gt;</c>
308 (important) tags all can contain one or more lines of text. Besides the
309 <c>&lt;table&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and
310 <c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
311 only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
312 Another thing -- these tags <e>should not</e> be stacked -- in other words,
313 don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
314 you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
315 exactly, making it well-suited for code excerpts. You must name the
316 <c>&lt;pre&gt;</c> tag with a <c>caption</c> attribute:
317 </p>
318
319 <pre caption="Named &lt;pre&gt;">
320 &lt;pre caption="Output of uptime"&gt;
321 # &lt;i&gt;uptime&lt;/i&gt;
322 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
323 &lt;/pre&gt;
324 </pre>
325
326 </body>
327 </section>
328 <section>
329 <title>Epigraphs</title>
330 <body>
331
332 <p by="Anonymous student">
333 Delegates from the original 13 states formed the Contented Congress. Thomas
334 Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
335 of Independence. Franklin discovered electricity by rubbing two cats backwards
336 and declared, "A horse divided against itself cannot stand." Franklin died in
337 1790 and is still dead.
338 </p>
339
340 <p>
341 Epigraphs are sometimes used at the beginning of chapters to illustrate what is
342 to follow. It is simply a paragraph with a <c>by</c> attribute that contains
343 the signature.
344 </p>
345
346 <pre caption="Short epigraph">
347 &lt;p by="Anonymous student"&gt;
348 Delegates from the original 13 states formed the...
349 &lt;/p&gt;
350 </pre>
351
352 </body>
353 </section>
354 <section>
355 <title>
356 &lt;path&gt;, &lt;c&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
357 </title>
358 <body>
359
360 <p>
361 The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
362 <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
363 <c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>.
364 </p>
365
366 <p>
367 The <c>&lt;path&gt;</c> element is used to mark text that refers to an
368 <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
369 <e>simple filename</e>. This element is generally rendered with a mono spaced
370 font to offset it from the standard paragraph type.
371 </p>
372
373 <p>
374 The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
375 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
376 that they can type in that will perform some kind of action. For example, all
377 the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
378 element because they represent something that the user could type in that is
379 not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
380 quickly identify commands that they need to type in. Also, because
381 <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
382 necessary to surround user input with double-quotes</e>. For example, don't
383 refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
384 the use of unnecessary double-quotes makes a document more readable -- and
385 adorable!
386 </p>
387
388 <p>
389 As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some
390 text.
391 </p>
392
393 <p>
394 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
395 I <e>really</e> should use semicolons more often. As you can see, this text is
396 offset from the regular paragraph type for emphasis. This helps to give your
397 prose more <e>punch</e>!
398 </p>
399
400 <p>
401 The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
402 <sub>subscript</sub> and <sup>superscript</sup>.
403 </p>
404
405 </body>
406 </section>
407 <section>
408 <title>Code samples and colour-coding</title>
409 <body>
410
411 <p>
412 To improve the readability of code samples, the following tags are allowed
413 inside <c>&lt;pre&gt;</c> blocks:
414 </p>
415
416 <dl>
417 <dt><c>&lt;i&gt;</c></dt>
418 <dd>Distinguishes user input from displayed text</dd>
419 <dt><c>&lt;comment&gt;</c></dt>
420 <dd>Comments relevant to the action(s) that appear after the comment</dd>
421 <dt><c>&lt;keyword&gt;</c></dt>
422 <dd>Denotes a keyword in the language used in the code sample
423 </dd>
424 <dt><c>&lt;ident&gt;</c></dt>
425 <dd>Used for an identifier
426 </dd>
427 <dt><c>&lt;const&gt;</c></dt>
428 <dd>Used for a constant
429 </dd>
430 <dt><c>&lt;stmt&gt;</c></dt>
431 <dd>Used for a statement
432 </dd>
433 <dt><c>&lt;var&gt;</c></dt>
434 <dd>Used for a variable
435 </dd>
436 </dl>
437
438 <note>
439 Remember that all leading and trailing spaces, and line breaks in
440 <c>&lt;pre&gt;</c> blocks will appear in the displayed html page.
441 </note>
442
443 <p>
444 Sample colour-coded <c>&lt;pre&gt;</c> block:
445 </p>
446
447 <pre caption="My first ebuild">
448 <comment># Copyright 1999-2006 <b>Gentoo Foundation</b>
449 # Distributed under the terms of the GNU General Public License v2
450 # &#36;Header: $</comment>
451
452 <ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
453 <ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
454 <ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
455
456 <ident>LICENSE</ident>=<const>"GPL-2"</const>
457 <ident>SLOT</ident>=<const>"0"</const>
458 <ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
459 <ident>IUSE</ident>=<const>""</const>
460
461 <stmt>src_compile()</stmt> {
462 <keyword>econf</keyword> --with-posix-regex || <keyword>die</keyword> <const>"econf failed"</const>
463 <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const>
464 }
465
466 <stmt>src_install()</stmt> {
467 <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const>
468
469 <keyword>dodoc</keyword> FAQ NEWS README
470 <keyword>dohtml</keyword> EXTENDING.html ctags.html
471 }
472 </pre>
473
474 </body>
475 </section>
476 <section>
477 <title>&lt;mail&gt; and &lt;uri&gt;</title>
478 <body>
479
480 <p>
481 We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
482 some text with a particular email address, and takes the form <c>&lt;mail
483 link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the
484 email address, you can use <c>&lt;mail&gt;foo@bar.com&lt;/mail&gt;</c>, this
485 would be displayed as <mail>foo@bar.com</mail>.
486 </p>
487
488 <p>
489 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
490 It has two forms -- the first can be used when you want to have the actual URI
491 displayed in the body text, such as this link to
492 <uri>http://forums.gentoo.org</uri>. To create this link, I typed
493 <c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
494 when you want to associate a URI with some other text -- for example, <uri
495 link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
496 link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
497 Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
498 to link to other parts of the Gentoo web site. For instance, a link to the <uri
499 link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
500 link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
501 even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
502 link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
503 </p>
504
505 </body>
506 </section>
507 <section>
508 <title>Figures</title>
509 <body>
510
511 <p>
512 Here's how to insert a figure into a document -- <c>&lt;figure
513 link="mygfx.png" short="my picture" caption="my favorite picture of all
514 time"/&gt;</c>. The <c>link</c> attribute points to the actual graphic image,
515 the <c>short</c> attribute specifies a short description (currently used for
516 the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
517 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
518 for adding images without captions, borders, etc.
519 </p>
520
521 </body>
522 </section>
523 <section>
524 <title>Tables</title>
525 <body>
526
527 <p>
528 Guide supports a simplified table syntax similar to that of HTML. To start a
529 table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
530 tag. However, for inserting actual table data, we <e>don't</e> support the
531 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
532 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
533 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
534 -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
535 first row.
536 </p>
537
538 <p>
539 Besides, both table headers (<c>&lt;th&gt;</c>) and table items
540 (<c>&lt;ti&gt;</c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to
541 span their content across rows, columns or both.
542 </p>
543
544 <p>
545 Furthermore, table items (<c>&lt;ti&gt;</c>) can be right-aligned or centered
546 with the <c>align</c> attribute. Table headers (<c>&lt;th&gt;</c>) are
547 automatically centered.
548 </p>
549
550 <table>
551 <tr>
552 <th colspan="4">This title spans 4 columns</th>
553 </tr>
554 <tr>
555 <th rowspan="6">This title spans 6 rows</th>
556 <ti>Item A1</ti>
557 <ti>Item A2</ti>
558 <ti>Item A3</ti>
559 </tr>
560 <tr>
561 <ti align="center">Item B1</ti>
562 <th colspan="2" rowspan="2">Blocky 2x2 title</th>
563 </tr>
564 <tr>
565 <ti align="right">Item C1</ti>
566 </tr>
567 <tr>
568 <ti colspan="3" align="center">Item D1..D3</ti>
569 </tr>
570 <tr>
571 <ti rowspan="2">Item E1..F1</ti>
572 <ti colspan="2" align="right">Item E2..E3</ti>
573 </tr>
574 <tr>
575 <ti colspan="2" align="right">Item F2..F3</ti>
576 </tr>
577 </table>
578
579 </body>
580 </section>
581 <section>
582 <title>Lists</title>
583 <body>
584
585 <p>
586 To create ordered or unordered lists, simply use the XHTML-style
587 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
588 appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
589 that you can have lists inside lists. Don't forget that you are writing XML and
590 that you must close all tags including list items unlike in HTML.
591 </p>
592
593 <p>
594 Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that
595 neither the definition term tag (<c>&lt;dt&gt;</c>) nor the definition data tag
596 (<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
597 admonitions. A definition list comprises:
598 </p>
599
600 <dl>
601 <dt><c>&lt;dl&gt;</c></dt>
602 <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
603 <dt><c>&lt;dt&gt;</c></dt>
604 <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
605 <dt><c>&lt;dd&gt;</c></dt>
606 <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
607 </dl>
608
609 <p>
610 The following list copied from <uri
611 link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
612 that a definition list can contain ordered and unordered lists. It may not
613 contain another definition list though.
614 </p>
615
616 <dl>
617 <dt><b>The ingredients:</b></dt>
618 <dd>
619 <ul>
620 <li>100 g. flour</li>
621 <li>10 g. sugar</li>
622 <li>1 cup water</li>
623 <li>2 eggs</li>
624 <li>salt, pepper</li>
625 </ul>
626 </dd>
627 <dt><b>The procedure:</b></dt>
628 <dd>
629 <ol>
630 <li>Mix dry ingredients thoroughly</li>
631 <li>Pour in wet ingredients</li>
632 <li>Mix for 10 minutes</li>
633 <li>Bake for one hour at 300 degrees</li>
634 </ol>
635 </dd>
636 <dt><b>Notes:</b></dt>
637 <dd>The recipe may be improved by adding raisins</dd>
638 </dl>
639
640 </body>
641 </section>
642 <section>
643 <title>Intra-document references</title>
644 <body>
645
646 <p>
647 Guide makes it really easy to reference other parts of the document using
648 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
649 One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
650 One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
651 Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
652 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
653 link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
654 link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
655 link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.
656 </p>
657
658 <p>
659 However, some guides change often and using such "counting" can lead to broken
660 links. In order to cope with this, you can define a name for a
661 <c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
662 the <c>id</c> attribute, and then point to that attribute, like this:
663 </p>
664
665 <pre caption="Using the id attribute">
666 &lt;chapter id="foo"&gt;
667 &lt;title&gt;This is foo!&lt;/title&gt;
668 ...
669 &lt;p&gt;
670 More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
671 &lt;/p&gt;
672 </pre>
673
674 </body>
675 </section>
676 <section>
677 <title>Disclaimers and obsolete documents</title>
678 <body>
679
680 <p>
681 A <c>disclaimer</c> attribute can be applied to guides and handbooks to display
682 a predefined disclaimer at the top of the document. The available disclaimers
683 are:
684 </p>
685
686 <ul>
687 <li>
688 <b>articles</b> is used for <uri link="/doc/en/articles/">republished
689 articles</uri>
690 </li>
691 <li>
692 <b>draft</b> is used to indicate a document is still being worked on and
693 should not be considered official
694 </li>
695 <li>
696 <b>oldbook</b> is used on old handbooks to indicate they are not maintained
697 anymore
698 </li>
699 <li><b>obsolete</b> is used to mark a document as obsolete.</li>
700 </ul>
701
702 <p>
703 When marking a document as obsolete, you might want to add a link to a new
704 version. The <c>redirect</c> attribute does just that. The user might be
705 automatically redirected to the new page but you should not rely on that
706 behaviour.
707 </p>
708
709 <pre caption="Disclaimer sample">
710 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
711 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
712 &lt;!-- &#36;Header&#36; --&gt;
713
714 &lt;guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
715 &lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
716
717 &lt;author title="Author"&gt;
718 ...
719 </pre>
720
721 </body>
722 </section>
723 </chapter>
724
725 <chapter>
726 <title>Coding Style</title>
727 <section>
728 <title>Introduction</title>
729 <body>
730
731 <p>
732 Since all Gentoo Documentation is a joint effort and several people will
733 most likely change existing documentation, a coding style is needed.
734 A coding style contains two sections. The first one is regarding
735 internal coding - how the XML-tags are placed. The second one is
736 regarding the content - how not to confuse the reader.
737 </p>
738
739 <p>
740 Both sections are described next.
741 </p>
742
743 </body>
744 </section>
745 <section>
746 <title>Internal Coding Style</title>
747 <body>
748
749 <p>
750 <b>Newlines</b> must be placed immediately after <e>every</e>
751 GuideXML-tag (both opening as closing), except for:
752 <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
753 <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
754 <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
755 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
756 <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
757 </p>
758
759 <p>
760 <b>Blank lines</b> must be placed immediately after <e>every</e>
761 <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
762 <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
763 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
764 <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
765 <c>&lt;impo&gt;</c> (opening tags only).
766 </p>
767
768 <p>
769 <b>Word-wrapping</b> must be applied at 80 characters except inside
770 <c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
771 choice (for instance when a URL exceeds the maximum amount of characters). The
772 editor must then wrap whenever the first whitespace occurs. You should try to
773 keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
774 columns to help console users.
775 </p>
776
777 <p>
778 <b>Indentation</b> may not be used, except with the XML-constructs of which the
779 parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
780 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>, <c>&lt;dl&gt;</c>, and
781 <c>&lt;author&gt;</c>. If indentation is used, it <e>must</e> be two spaces for
782 each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
783 Besides, tabs are not allowed in GuideXML documents.
784 </p>
785
786 <p>
787 In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>,
788 <c>&lt;li&gt;</c> or <c>&lt;dd&gt;</c> constructs, indentation must be used for
789 the content.
790 </p>
791
792 <p>
793 An example for indentation is:
794 </p>
795
796 <pre caption="Indentation Example">
797 &lt;table&gt;
798 &lt;tr&gt;
799 &lt;th&gt;Foo&lt;/th&gt;
800 &lt;th&gt;Bar&lt;/th&gt;
801 &lt;/tr&gt;
802 &lt;tr&gt;
803 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
804 &lt;ti&gt;
805 In case text cannot be shown within an 80-character wide line, you
806 must use indentation if the parent tag allows it
807 &lt;/ti&gt;
808 &lt;/tr&gt;
809 &lt;/table&gt;
810
811 &lt;ul&gt;
812 &lt;li&gt;First option&lt;/li&gt;
813 &lt;li&gt;Second option&lt;/li&gt;
814 &lt;/ul&gt;
815 </pre>
816
817 <p>
818 <b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
819 and the attribute value. As an example:
820 </p>
821
822 <pre caption="Attributes">
823 <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
824 <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
825 </pre>
826
827 </body>
828 </section>
829 <section>
830 <title>External Coding Style</title>
831 <body>
832
833 <p>
834 Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c>,
835 <c>&lt;ol&gt;</c>) and <c>&lt;dl&gt;</c>, periods (".") should not be used
836 unless multiple sentences are used. In that case, every sentence should end
837 with a period (or other reading marks).
838 </p>
839
840 <p>
841 Every sentence, including those inside tables and listings, should start
842 with a capital letter.
843 </p>
844
845 <pre caption="Periods and capital letters">
846 &lt;ul&gt;
847 &lt;li&gt;No period&lt;/li&gt;
848 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
849 &lt;/ul&gt;
850 </pre>
851
852 <p>
853 Code Listings should <e>always</e> have a <c>caption</c>.
854 </p>
855
856 <p>
857 Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
858 possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
859 Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
860 </p>
861
862 <p>
863 When you comment something inside a <c>&lt;pre&gt;</c> construct, use
864 <c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
865 that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
866 for C code, etc.) Also place the comment <e>before</e> the subject of the
867 comment.
868 </p>
869
870 <pre caption="Comment example">
871 <comment>(Substitute "john" with your user name)</comment>
872 # <i>id john</i>
873 </pre>
874
875 </body>
876 </section>
877 </chapter>
878
879 <chapter>
880 <title>Handbook Format</title>
881 <section>
882 <title>Guide vs Book</title>
883 <body>
884
885 <p>
886 For high-volume documentation, such as the <uri
887 link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
888 broader format was needed. We designed a GuideXML-compatible enhancement that
889 allows us to write modular and multi-page documentation.
890 </p>
891
892 </body>
893 </section>
894 <section>
895 <title>Main File</title>
896 <body>
897
898 <p>
899 The first change is the need for a "master" document. This document contains no
900 real content, but links to the individual documentation modules. The syntax
901 doesn't differ much from GuideXML:
902 </p>
903
904 <pre caption="Example book usage">
905 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
906 &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
907 &lt;!-- &#36;Header&#36; --&gt;
908
909 &lt;<i>book</i> link="example.xml"&gt;
910 &lt;title&gt;Example Book Usage&lt;/title&gt;
911
912 &lt;author...&gt;
913 ...
914 &lt;/author&gt;
915
916 &lt;abstract&gt;
917 ...
918 &lt;/abstract&gt;
919
920 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
921 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
922 &lt;license/&gt;
923
924 &lt;version&gt;...&lt;/version&gt;
925 &lt;date&gt;...&lt;/date&gt;
926 </pre>
927
928 <p>
929 So far no real differences (except for the <c>&lt;book&gt;</c> instead of
930 <c>&lt;guide&gt;</c> tag). Instead of starting with the individual
931 <c>&lt;chapter&gt;</c>s, you define a <c>&lt;part&gt;</c>, which is the
932 equivalent of a separate part in a book:
933 </p>
934
935 <pre caption="Defining a part">
936 &lt;part&gt;
937 &lt;title&gt;Part One&lt;/title&gt;
938 &lt;abstract&gt;
939 ...
940 &lt;/abstract&gt;
941
942 <comment>(Defining the several chapters)</comment>
943 &lt;/part&gt;
944 </pre>
945
946 <p>
947 Each part is accompanied by a <c>&lt;title&gt;</c> and an
948 <c>&lt;abstract&gt;</c> which gives a small introduction to the part.
949 </p>
950
951 <p>
952 Inside each part, you define the individual <c>&lt;chapter&gt;</c>s. Each
953 chapter <e>must</e> be a separate document. As a result it is no surprise that
954 a special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
955 document.
956 </p>
957
958 <pre caption="Defining a chapter">
959 &lt;chapter&gt;
960 &lt;title&gt;Chapter One&lt;/title&gt;
961 &lt;abstract&gt;
962 This is a small explanation on chapter one.
963 &lt;/abstract&gt;
964
965 &lt;include href="path/to/chapter-one.xml"/&gt;
966
967 &lt;/chapter&gt;
968 </pre>
969
970 </body>
971 </section>
972 <section>
973 <title>Designing the Individual Chapters</title>
974 <body>
975
976 <p>
977 The content of an individual chapter is structured as follows:
978 </p>
979
980 <pre caption="Chapter Syntax">
981 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
982 &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
983 &lt;!-- &#36;Header&#36; --&gt;
984
985 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
986 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
987
988 &lt;sections&gt;
989
990 &lt;version&gt;...&lt;/version&gt;
991 &lt;date&gt;...&lt;/date&gt;
992
993 <comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
994
995 &lt;/sections&gt;
996 </pre>
997
998 <p>
999 Inside each chapter you can define <c>&lt;section&gt;</c>s (equivalent of
1000 <c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>s (equivalent
1001 of <c>&lt;section&gt;</c> in a Guide).
1002 </p>
1003
1004 <p>
1005 Each individual chapter should have its own date and version elements. The
1006 latest date of all chapters and master document will be displayed when a user
1007 browses through all parts of the book.
1008 </p>
1009
1010 </body>
1011 </section>
1012 </chapter>
1013
1014 <chapter>
1015 <title>Resources</title>
1016 <section>
1017 <title>Start writing</title>
1018 <body>
1019
1020 <p>
1021 Guide has been specially designed to be "lean and mean" so that developers can
1022 spend more time writing documentation and less time learning the actual XML
1023 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
1024 to start writing quality Gentoo documentation. You might be interested
1025 in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation
1026 Development Tips &amp; Tricks</uri>. If you'd like to help (or have any
1027 questions about guide), please post a message to the <uri
1028 link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd
1029 like to tackle. Have fun!
1030 </p>
1031
1032 </body>
1033 </section>
1034 </chapter>
1035 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20