/[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.44 - (show annotations) (download) (as text)
Mon May 23 19:05:33 2005 UTC (9 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.43: +12 -6 lines
File MIME type: application/xml
#93304 - Martin reported two important but missing aspects: explanation on <i> and the non-availability of <c> in the Coding Style list

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

  ViewVC Help
Powered by ViewVC 1.1.20