1 |
<?xml version="1.0" encoding="UTF-8"?> |
2 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.47 2005/07/26 11:51:06 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.5 --> |
33 |
<license/> |
34 |
|
35 |
<version>2.24</version> |
36 |
<date>2005-08-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 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 |
<?xml version="1.0" encoding="UTF-8"?> |
87 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
88 |
<!-- $Header$ --> |
89 |
|
90 |
<guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"> |
91 |
<title><i>Gentoo Linux Documentation Guide</i></title> |
92 |
<author title="<i>Author</i>"> |
93 |
<mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail> |
94 |
</author> |
95 |
|
96 |
<abstract> |
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 |
</abstract> |
102 |
|
103 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
104 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
105 |
<license/> |
106 |
|
107 |
<version><i>1.0</i></version> |
108 |
<date><i>2004-12-25</i></date> |
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><!-- $Header$ --></c> line |
114 |
will be automatically modified by the CVS server and helps to track revisions. |
115 |
Next, there's a <c><guide></c> tag -- the entire guide document is |
116 |
enclosed within a <c><guide> </guide></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><title></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><author></c> tags, which contain information |
134 |
about the various authors of the document. Each <c><author></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><mail></c> tag, used to specify an email address for this particular |
139 |
person. The <c><mail></c> tag is optional and can be omitted, and no |
140 |
more than one <c><author></c> element is required per guide document. |
141 |
</p> |
142 |
|
143 |
<p> |
144 |
Next, we come to the <c><abstract></c>, <c><version></c> and |
145 |
<c><date></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><title></c> and <c><mail></c> tags, these |
154 |
tags shouldn't appear anywhere else except immediately inside the |
155 |
<c><guide></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><license/></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></guide></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 |
<chapter> |
185 |
<title><i>This is my chapter</i></title> |
186 |
<section> |
187 |
<title><i>This is section one of my chapter</i></title> |
188 |
<body> |
189 |
|
190 |
<p> |
191 |
<i>This is the actual text content of my section.</i> |
192 |
</p> |
193 |
|
194 |
</body> |
195 |
</section> |
196 |
</chapter> |
197 |
</pre> |
198 |
|
199 |
<p> |
200 |
Above, I set the chapter title by adding a child <c><title></c> |
201 |
element to the <c><chapter></c> element. Then, I created a section by |
202 |
adding a <c><section></c> element. If you look inside the |
203 |
<c><section></c> element, you'll see that it has two child elements -- a |
204 |
<c><title></c> and a <c><body></c>. While the <c><title></c> |
205 |
is nothing new, the <c><body></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><body></c> element in a bit. |
208 |
</p> |
209 |
|
210 |
<note> |
211 |
A <c><guide></c> element can contain multiple <c><chapter></c> |
212 |
elements, and a <c><chapter></c> can contain multiple |
213 |
<c><section></c> elements. However, a <c><section></c> |
214 |
element can only contain one <c><body></c> element. |
215 |
</note> |
216 |
|
217 |
</body> |
218 |
</section> |
219 |
<section> |
220 |
<title>An example <body></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><body></c> element: |
226 |
</p> |
227 |
|
228 |
<pre caption="Example of a body element"> |
229 |
<p> |
230 |
This is a paragraph. <path>/etc/passwd</path> is a file. |
231 |
<uri>http://forums.gentoo.org</uri> is my favorite website. |
232 |
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
233 |
</p> |
234 |
|
235 |
<pre caption="Code Sample"> |
236 |
This is text output or code. |
237 |
# <i>this is user input</i> |
238 |
|
239 |
Make HTML/XML easier to read by using selective emphasis: |
240 |
<foo><i>bar</i></foo> |
241 |
|
242 |
<comment>(This is how to insert an inline note into the code block)</comment> |
243 |
</pre> |
244 |
|
245 |
<note> |
246 |
This is a note. |
247 |
</note> |
248 |
|
249 |
<warn> |
250 |
This is a warning. |
251 |
</warn> |
252 |
|
253 |
<impo> |
254 |
This is important. |
255 |
</impo> |
256 |
</pre> |
257 |
|
258 |
<p> |
259 |
Now, here's how the <c><body></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 web site. |
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 |
<foo><i>bar</i></foo> |
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 <body> 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><p></c> (paragraph), <c><pre></c> (code |
299 |
block), <c><note></c>, <c><warn></c> (warning) and |
300 |
<c><impo></c> (important) tags all can contain one or more lines of text. |
301 |
Besides the <c><table></c> element (which we'll cover in just a bit), |
302 |
these are the only tags that should appear immediately inside a |
303 |
<c><body></c> element. Another thing -- these tags <e>should not</e> be |
304 |
stacked -- in other words, don't put a <c><note></c> element inside a |
305 |
<c><p></c> element. As you might guess, the <c><pre></c> element |
306 |
preserves its whitespace exactly, making it well-suited for code excerpts. |
307 |
You can also name the <c><pre></c> tag: |
308 |
</p> |
309 |
|
310 |
<pre caption="Named <pre>"> |
311 |
<pre caption = "Output of uptime"> |
312 |
# <i>uptime</i> |
313 |
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
314 |
</pre> |
315 |
</pre> |
316 |
|
317 |
</body> |
318 |
</section> |
319 |
<section> |
320 |
<title><path>, <c>, <i> and <e></title> |
321 |
<body> |
322 |
|
323 |
<p> |
324 |
The <c><path></c>, <c><c></c> and <c><e></c> elements can |
325 |
be used inside any child <c><body></c> tag, except for |
326 |
<c><pre></c>. The <c><i></c> element can only be used inside |
327 |
<c><pre></c>. |
328 |
</p> |
329 |
|
330 |
<p> |
331 |
The <c><path></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 mono spaced |
334 |
font to offset it from the standard paragraph type. |
335 |
</p> |
336 |
|
337 |
<p> |
338 |
The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
339 |
input</e>. Think of <c><c></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><c></c> |
342 |
element because they represent something that the user could type in that is |
343 |
not a path. By using <c><c></c> elements, you'll help your readers |
344 |
quickly identify commands that they need to type in. Also, because |
345 |
<c><c></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><c></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><pre></c>, |
354 |
use <c><i></c> instead. |
355 |
</p> |
356 |
|
357 |
<p> |
358 |
<c><e></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><mail> and <uri></title> |
368 |
<body> |
369 |
|
370 |
<p> |
371 |
We've taken a look at the <c><mail></c> tag earlier; it's used to link |
372 |
some text with a particular email address, and takes the form <c><mail |
373 |
link="foo@bar.com">Mr. Foo Bar</mail></c>. |
374 |
</p> |
375 |
|
376 |
<p> |
377 |
The <c><uri></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><uri>http://forums.gentoo.org</uri></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><uri link="http://forums.gentoo.org">the Gentoo |
385 |
Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> |
386 |
to link to other parts of the Gentoo web site. For instance, a link to the <uri |
387 |
link="/doc/en/">documentation main index</uri> should be simply <c><uri |
388 |
link="/doc/en/index.xml">documentation main index</uri></c>. You can |
389 |
even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri |
390 |
link="/doc/en/">documentation main index</uri></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><figure |
401 |
link="mygfx.png" short="my picture" caption="my favorite picture of all |
402 |
time"/></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 <img src="foo.gif"/> 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><table></c> tag. Start a row with a <c><tr></c> |
418 |
tag. However, for inserting actual table data, we <e>don't</e> support the |
419 |
HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
420 |
header, and <c><ti></c> if you are inserting a normal informational |
421 |
block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
422 |
-- there's no requirement that <c><th></c> elements appear only in the |
423 |
first row. Currently, these tags don't support any attributes, but some might |
424 |
be added (such as a <c>caption=</c> attribute for <c><table></c>) later. |
425 |
</p> |
426 |
|
427 |
<p> |
428 |
To create ordered or unordered lists, simply use the XHTML-style |
429 |
<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags |
430 |
should only appear inside a <c><body></c>, <c><ul></c> or |
431 |
<c><ol></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><uri link="#doc_chap1">Chapter |
445 |
One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
446 |
Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
447 |
Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
448 |
link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri |
449 |
link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri |
450 |
link="#doc_chap2_pre2">code listing 2.2</uri></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><chapter></c>, <c><section></c> or a <c><tr></c> by using |
458 |
the <c>id</c> attribute, and then point to that attribute, like this: |
459 |
</p> |
460 |
|
461 |
<pre caption="Using the id attribute"> |
462 |
<chapter id="foo"> |
463 |
<title>This is foo!</title> |
464 |
... |
465 |
<p> |
466 |
More information can be found in the <uri link="#foo">foo chapter</uri> |
467 |
</p> |
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><version></c>, <c><date></c>, <c><title></c>, |
502 |
<c><th></c>, <c><ti></c>, |
503 |
<c><li></c>, <c><i></c>, <c><e></c>, |
504 |
<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>, |
505 |
<c><comment></c>, <c><mail></c>. |
506 |
</p> |
507 |
|
508 |
<p> |
509 |
<b>Blank lines</b> must be placed immediately after <e>every</e> |
510 |
<c><body></c> (opening tag only) and before <e>every</e> |
511 |
<c><chapter></c>, <c><p></c>, <c><table></c>, |
512 |
<c><author></c> (set), <c><pre></c>, <c><ul></c>, |
513 |
<c><ol></c>, <c><warn></c>, <c><note></c> and |
514 |
<c><impo></c> (opening tags only). |
515 |
</p> |
516 |
|
517 |
<p> |
518 |
<b>Word-wrapping</b> must be applied at 80 characters except inside |
519 |
<c><pre></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><tr></c> (from <c><table></c>), |
527 |
<c><ul></c>, <c><ol></c> and <c><author></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><ti></c>, <c><th></c> or |
534 |
<c><li></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 |
<table> |
543 |
<tr> |
544 |
<th>Foo</th> |
545 |
<th>Bar</th> |
546 |
</tr> |
547 |
<tr> |
548 |
<ti>This is an example for indentation</ti> |
549 |
<ti> |
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 |
</ti> |
553 |
</tr> |
554 |
</table> |
555 |
|
556 |
<ul> |
557 |
<li>First option</li> |
558 |
<li>Second option</li> |
559 |
</ul> |
560 |
</pre> |
561 |
|
562 |
<p> |
563 |
<b>Attributes</b> may not have spaces in between the attribute, the |
564 |
"=" mark, and the attribute value. As an example: |
565 |
</p> |
566 |
|
567 |
<pre caption="Attributes"> |
568 |
<comment>Wrong :</comment> <pre caption = "Attributes"> |
569 |
<comment>Correct:</comment> <pre caption="Attributes"> |
570 |
</pre> |
571 |
|
572 |
</body> |
573 |
</section> |
574 |
<section> |
575 |
<title>External Coding Style</title> |
576 |
<body> |
577 |
|
578 |
<p> |
579 |
Inside tables (<c><table></c>) and listings (<c><ul></c> and |
580 |
<c><ol></c>), periods (".") 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 |
<ul> |
592 |
<li>No period</li> |
593 |
<li>With period. Multiple sentences, remember?</li> |
594 |
</ul> |
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><uri></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><pre></c> construct, use |
609 |
<c><comment></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 |
<?xml version='1.0' encoding='UTF-8'?> |
651 |
<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
652 |
<!-- $Header$ --> |
653 |
|
654 |
<<i>book</i> link="example.xml"> |
655 |
<title>Example Book Usage</title> |
656 |
|
657 |
<author...> |
658 |
... |
659 |
</author> |
660 |
|
661 |
<abstract> |
662 |
... |
663 |
</abstract> |
664 |
|
665 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
666 |
<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
667 |
<license/> |
668 |
|
669 |
<version>...</version> |
670 |
<date>...</date> |
671 |
</pre> |
672 |
|
673 |
<p> |
674 |
So far no real differences (except for the <c><book></c> instead of |
675 |
<c><guide></c> tag). Instead of starting with the individual |
676 |
<c><chapter></c>'s, you define a <c><part></c>, which is the |
677 |
equivalent of a separate part in a book: |
678 |
</p> |
679 |
|
680 |
<pre caption="Defining a part"> |
681 |
<part> |
682 |
<title>Part One</title> |
683 |
<abstract> |
684 |
... |
685 |
</abstract> |
686 |
|
687 |
<comment>(Defining the several chapters)</comment> |
688 |
</part> |
689 |
</pre> |
690 |
|
691 |
<p> |
692 |
Each part is accompanied by a <c><title></c> and an |
693 |
<c><abstract></c> which gives a small introduction to the part. |
694 |
</p> |
695 |
|
696 |
<p> |
697 |
Inside each part, you define the individual <c><chapter></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><include></c>) is added to allow including the separate |
700 |
document. |
701 |
</p> |
702 |
|
703 |
<pre caption="Defining a chapter"> |
704 |
<chapter> |
705 |
<title>Chapter One</title> |
706 |
<abstract> |
707 |
This is a small explanation on chapter one. |
708 |
</abstract> |
709 |
|
710 |
<include href="path/to/chapter-one.xml"/> |
711 |
|
712 |
</chapter> |
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 |
<?xml version='1.0' encoding='UTF-8'?> |
727 |
<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
728 |
<!-- $Header$ --> |
729 |
|
730 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
731 |
<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
732 |
|
733 |
<sections> |
734 |
|
735 |
<version>...</version> |
736 |
<date>...</date> |
737 |
|
738 |
<comment>(Define the several <section> and <subsection>)</comment> |
739 |
|
740 |
</sections> |
741 |
</pre> |
742 |
|
743 |
<p> |
744 |
Inside each chapter you can define <c><section></c>'s (equivalent of |
745 |
<c><chapter></c> in a Guide) and <c><subsection></c>'s (equivalent |
746 |
of <c><section></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 & 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> |