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