/[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.49 - (show annotations) (download) (as text)
Tue Aug 23 09:18:12 2005 UTC (9 years, 1 month ago) by neysx
Branch: MAIN
Changes since 1.48: +7 -6 lines
File MIME type: application/xml
#103418 Added missing blank line. Also bumped license to 2.5

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

  ViewVC Help
Powered by ViewVC 1.1.20