1 |
neysx 07/10/04 19:37:23 |
2 |
|
3 |
Modified: xml-guide.xml |
4 |
Log: |
5 |
Documented recent and much less recent features: |
6 |
. shortcut for Gentoo devs in <mail> |
7 |
. @link is not compulsory |
8 |
. handbook values & conditionals |
9 |
. <faqindex> |
10 |
Used GuideXML more consistently |
11 |
|
12 |
Revision Changes Path |
13 |
1.67 xml/htdocs/doc/en/xml-guide.xml |
14 |
|
15 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?rev=1.67&view=markup |
16 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?rev=1.67&content-type=text/plain |
17 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?r1=1.66&r2=1.67 |
18 |
|
19 |
Index: xml-guide.xml |
20 |
=================================================================== |
21 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v |
22 |
retrieving revision 1.66 |
23 |
retrieving revision 1.67 |
24 |
diff -u -r1.66 -r1.67 |
25 |
--- xml-guide.xml 29 Nov 2006 15:48:57 -0000 1.66 |
26 |
+++ xml-guide.xml 4 Oct 2007 19:37:23 -0000 1.67 |
27 |
@@ -1,12 +1,12 @@ |
28 |
<?xml version="1.0" encoding="UTF-8"?> |
29 |
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.66 2006/11/29 15:48:57 nightmorph Exp $ --> |
30 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.67 2007/10/04 19:37:23 neysx Exp $ --> |
31 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
32 |
|
33 |
-<guide link="/doc/en/xml-guide.xml"> |
34 |
-<title>Gentoo XML Guide</title> |
35 |
+<guide> |
36 |
+<title>Gentoo GuideXML Guide</title> |
37 |
|
38 |
<author title="Author"> |
39 |
- <mail link="neysx@g.o">Xavier Neys</mail> |
40 |
+ <mail link="neysx"/> |
41 |
</author> |
42 |
<author title="Author"> |
43 |
<mail link="drobbins@g.o">Daniel Robbins</mail> |
44 |
@@ -32,17 +32,17 @@ |
45 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
46 |
<license/> |
47 |
|
48 |
-<version>7</version> |
49 |
-<date>2006-05-11</date> |
50 |
+<version>8</version> |
51 |
+<date>2007-10-04</date> |
52 |
|
53 |
<chapter> |
54 |
-<title>Guide basics</title> |
55 |
+<title>GuideXML basics</title> |
56 |
<section> |
57 |
-<title>Guide XML design goals</title> |
58 |
+<title>GuideXML design goals</title> |
59 |
<body> |
60 |
|
61 |
<p> |
62 |
-The guide XML syntax is lightweight yet expressive, so that it is easy to |
63 |
+The guideXML syntax is lightweight yet expressive, so that it is easy to |
64 |
learn yet also provides all the features we need for the creation of web |
65 |
documentation. The number of tags is kept to a minimum -- just those we need. |
66 |
This makes it easy to transform guide into other formats, such as DocBook |
67 |
@@ -50,7 +50,7 @@ |
68 |
</p> |
69 |
|
70 |
<p> |
71 |
-The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML |
72 |
+The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML |
73 |
documents. |
74 |
</p> |
75 |
|
76 |
@@ -77,7 +77,7 @@ |
77 |
</chapter> |
78 |
|
79 |
<chapter> |
80 |
-<title>Guide XML</title> |
81 |
+<title>GuideXML</title> |
82 |
<section> |
83 |
<title>Basic structure</title> |
84 |
<body> |
85 |
@@ -119,17 +119,19 @@ |
86 |
document and specifies its DTD. The <c><!-- $Header$ --></c> line |
87 |
will be automatically modified by the CVS server and helps to track revisions. |
88 |
Next, there's a <c><guide></c> tag -- the entire guide document is |
89 |
-enclosed within a <c><guide> </guide></c> pair. The <c>link</c> |
90 |
-attribute is compulsory and should preferably contain the absolute path to the |
91 |
-document relatively to the document root even though the file name alone will |
92 |
-work. It is mainly used to generate a link to a printer-friendly version of |
93 |
-your document. If you use a wrong value, the link to the printable version will |
94 |
-either not work or point to a wrong document. Translated documents <e>must</e> |
95 |
-specify the full path because it is also used to check whether a more recent |
96 |
-original document exists. The <c>lang</c> attribute should be used to specify |
97 |
-the language code of your document. It is used to format the date and insert |
98 |
-strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language. |
99 |
-The default is English. |
100 |
+enclosed within a <c><guide> </guide></c> pair. |
101 |
+<br/> |
102 |
+The <c>link</c> attribute is optional and should preferably contain the |
103 |
+absolute path to the document relatively to the document root even though the |
104 |
+file name alone will work. It is only used to generate a link to a |
105 |
+printer-friendly version of your document and check whether a translation is |
106 |
+up-to-date. Our XSL back-engine passes the actual path to our XSL stylesheet. |
107 |
+The link attribute is only used as a fall-back value in case the XML is |
108 |
+processed by other means. |
109 |
+<br/> |
110 |
+The <c>lang</c> attribute should be used to specify the language code of your |
111 |
+document. It is used to format the date and insert strings like "<e>Note</e>", |
112 |
+"<e>Content</e>", etc. in the specified language. The default is English. |
113 |
</p> |
114 |
|
115 |
<p> |
116 |
@@ -144,8 +146,8 @@ |
117 |
relationship to the document (author, co-author, editor, etc.). In this |
118 |
particular example, the authors' names are enclosed in another tag -- a |
119 |
<c><mail></c> tag, used to specify an email address for this particular |
120 |
-person. The <c><mail></c> tag is optional and can be omitted, and no |
121 |
-more than one <c><author></c> element is required per guide document. |
122 |
+person. The <c><mail></c> tag is optional and can be omitted, and at |
123 |
+least one <c><author></c> element is required per guide document. |
124 |
</p> |
125 |
|
126 |
<p> |
127 |
@@ -157,9 +159,9 @@ |
128 |
</p> |
129 |
|
130 |
<p> |
131 |
-This rounds out the tags that should appear at the beginning of a guide |
132 |
-document. Besides the <c><title></c> and <c><mail></c> tags, these |
133 |
-tags shouldn't appear anywhere else except immediately inside the |
134 |
+This sums up the tags that should appear at the beginning of a guide document. |
135 |
+Besides the <c><title></c> and <c><mail></c> tags, these tags |
136 |
+shouldn't appear anywhere else except immediately inside the |
137 |
<c><guide></c> tag, and for consistency it's recommended (but not |
138 |
required) that these tags appear before the content of the document. |
139 |
</p> |
140 |
@@ -216,10 +218,10 @@ |
141 |
</p> |
142 |
|
143 |
<note> |
144 |
-A <c><guide></c> element can contain multiple <c><chapter></c> |
145 |
-elements, and a <c><chapter></c> can contain multiple |
146 |
-<c><section></c> elements. However, a <c><section></c> |
147 |
-element can only contain one <c><body></c> element. |
148 |
+A <c><guide></c> element must contain at least one <c><chapter></c> |
149 |
+elements, a <c><chapter></c> must contain at least one |
150 |
+<c><section></c> elements and a <c><section></c> element must |
151 |
+contain at least one <c><body></c> element. |
152 |
</note> |
153 |
|
154 |
</body> |
155 |
@@ -480,26 +482,51 @@ |
156 |
<p> |
157 |
We've taken a look at the <c><mail></c> tag earlier; it's used to link |
158 |
some text with a particular email address, and takes the form <c><mail |
159 |
-link="foo@×××.com">Mr. Foo Bar</mail></c>. If you want to display the |
160 |
-email address, you can use <c><mail>foo@×××.com</mail></c>, this |
161 |
-would be displayed as <mail>foo@×××.com</mail>. |
162 |
+link="foo.bar@×××××××.com">Mr. Foo Bar</mail></c>. If you want to display the |
163 |
+email address, you can use <c><mail>foo.bar@×××××××.com</mail></c>, this |
164 |
+would be displayed as <mail>foo.bar@×××××××.com</mail>. |
165 |
+</p> |
166 |
+ |
167 |
+<p> |
168 |
+Shorter forms make it easier to use names and emails of Gentoo developers. Both |
169 |
+<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c> |
170 |
+would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email |
171 |
+with a different content than his full name, use the second form with some |
172 |
+content. For instance, use a dev's first name: <c><mail |
173 |
+link="neysx">Xavier</mail></c> appears as <mail |
174 |
+link="neysx">Xavier</mail>. |
175 |
+<br/> |
176 |
+This is particularly useful when you want to name a developer whose name |
177 |
+contains "funny" characters that you can't type. |
178 |
</p> |
179 |
|
180 |
<p> |
181 |
The <c><uri></c> tag is used to point to files/locations on the Internet. |
182 |
It has two forms -- the first can be used when you want to have the actual URI |
183 |
displayed in the body text, such as this link to |
184 |
-<uri>http://forums.gentoo.org</uri>. To create this link, I typed |
185 |
-<c><uri>http://forums.gentoo.org</uri></c>. The alternate form is |
186 |
+<uri>http://forums.gentoo.org/</uri>. To create this link, I typed |
187 |
+<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is |
188 |
when you want to associate a URI with some other text -- for example, <uri |
189 |
-link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e> |
190 |
-link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo |
191 |
-Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> |
192 |
-to link to other parts of the Gentoo web site. For instance, a link to the <uri |
193 |
-link="/doc/en/">documentation main index</uri> should be simply <c><uri |
194 |
-link="/doc/en/index.xml">documentation main index</uri></c>. You can |
195 |
-even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri |
196 |
-link="/doc/en/">documentation main index</uri></c>. |
197 |
+link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create |
198 |
+<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the |
199 |
+Gentoo Forums</uri></c>. You don't need to write |
200 |
+<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site. |
201 |
+For instance, a link to the <uri link="/doc/en/">documentation main index</uri> |
202 |
+should be simply <c><uri link="/doc/en/index.xml">documentation main |
203 |
+index</uri></c>. You can even omit <c>index.xml</c> when you link to a |
204 |
+directory index, e.g. <c><uri link="/doc/en/">documentation main |
205 |
+index</uri></c>. Leaving the trailing slash saves an extra HTTP request. |
206 |
+</p> |
207 |
+ |
208 |
+<p> |
209 |
+You should not use a <c><uri></c> tag with a <c>link</c> attribute that |
210 |
+starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag. |
211 |
+</p> |
212 |
+ |
213 |
+<p> |
214 |
+Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here |
215 |
+syndrome</uri> as recommended by the <uri |
216 |
+link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>. |
217 |
</p> |
218 |
|
219 |
</body> |
220 |
@@ -525,10 +552,10 @@ |
221 |
<body> |
222 |
|
223 |
<p> |
224 |
-Guide supports a simplified table syntax similar to that of HTML. To start a |
225 |
+GuideXML supports a simplified table syntax similar to that of HTML. To start a |
226 |
table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
227 |
-tag. However, for inserting actual table data, we <e>don't</e> support the |
228 |
-HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
229 |
+tag. However, for inserting actual table data, we <e>don't</e> support the HTML |
230 |
+<td> tag; instead, use the <c><th></c> if you are inserting a |
231 |
header, and <c><ti></c> if you are inserting a normal informational |
232 |
block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
233 |
-- there's no requirement that <c><th></c> elements appear only in the |
234 |
@@ -644,15 +671,15 @@ |
235 |
<body> |
236 |
|
237 |
<p> |
238 |
-Guide makes it really easy to reference other parts of the document using |
239 |
+GuideXML makes it really easy to reference other parts of the document using |
240 |
hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
241 |
One</uri> by typing <c><uri link="#doc_chap1">Chapter |
242 |
One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
243 |
Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
244 |
-Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
245 |
-link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri |
246 |
-link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri |
247 |
-link="#doc_chap2_pre2">code listing 2.2</uri></c>. |
248 |
+Chapter One</uri></c>. To refer to figure 3 in chapter 1, type |
249 |
+<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer |
250 |
+to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type |
251 |
+<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>. |
252 |
</p> |
253 |
|
254 |
<p> |
255 |
@@ -711,7 +738,7 @@ |
256 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
257 |
<!-- $Header$ --> |
258 |
|
259 |
-<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> |
260 |
+<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> |
261 |
<title>Gentoo x86 Installation Guide</title> |
262 |
|
263 |
<author title="Author"> |
264 |
@@ -720,9 +747,312 @@ |
265 |
|
266 |
</body> |
267 |
</section> |
268 |
+<section> |
269 |
+<title>FAQs</title> |
270 |
+<body> |
271 |
+ |
272 |
+<p> |
273 |
+FAQ documents need to start with a list of questions with links to their |
274 |
+answers. Creating such a list is both time-consuming and error-prone. The list |
275 |
+can be created automatically if you use a <c>faqindex</c> element as the first |
276 |
+chapter of your document. This element has the same structure as a |
277 |
+<c>chapter</c> to allow some introductory text. The structure of the document |
278 |
+is expected to be split into chapters (at least one chapter) containing |
279 |
+sections, each section containing one question specified in its <c>title</c> |
280 |
+element with the answer in its <c>body</c>. The FAQ index will appear as one |
281 |
+section per chapter and one link per question. |
282 |
+</p> |
283 |
+ |
284 |
+<p> |
285 |
+A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri |
286 |
+link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above |
287 |
+obvious. |
288 |
+</p> |
289 |
+ |
290 |
+</body> |
291 |
+</section> |
292 |
+</chapter> |
293 |
+ |
294 |
+<chapter> |
295 |
+<title>Handbook Format</title> |
296 |
+<section> |
297 |
+<title>Guide vs Book</title> |
298 |
+<body> |
299 |
+ |
300 |
+<p> |
301 |
+For high-volume documentation, such as the <uri |
302 |
+link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
303 |
+broader format was needed. We designed a GuideXML-compatible enhancement that |
304 |
+allows us to write modular and multi-page documentation. |
305 |
+</p> |
306 |
+ |
307 |
+</body> |
308 |
+</section> |
309 |
+<section> |
310 |
+<title>Main File</title> |
311 |
+<body> |
312 |
+ |
313 |
+<p> |
314 |
+The first change is the need for a "master" document. This document contains no |
315 |
+real content, but links to the individual documentation modules. The syntax |
316 |
+doesn't differ much from GuideXML: |
317 |
+</p> |
318 |
+ |
319 |
+<pre caption="Example book usage"> |
320 |
+<?xml version='1.0' encoding='UTF-8'?> |
321 |
+<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
322 |
+<!-- $Header$ --> |
323 |
+ |
324 |
+<<i>book</i>> |
325 |
+<title>Example Book Usage</title> |
326 |
+ |
327 |
+<author...> |
328 |
+ ... |
329 |
+</author> |
330 |
+ |
331 |
+<abstract> |
332 |
+ ... |
333 |
+</abstract> |
334 |
+ |
335 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
336 |
+<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
337 |
+<license/> |
338 |
+ |
339 |
+<version>...</version> |
340 |
+<date>...</date> |
341 |
+</pre> |
342 |
+ |
343 |
+<p> |
344 |
+So far no real differences (except for the <c><book></c> instead of |
345 |
+<c><guide></c> tag). Instead of starting with the individual |
346 |
+<c><chapter></c>s, you define a <c><part></c>, which is the |
347 |
+equivalent of a separate part in a book: |
348 |
+</p> |
349 |
+ |
350 |
+<pre caption="Defining a part"> |
351 |
+<part> |
352 |
+<title>Part One</title> |
353 |
+<abstract> |
354 |
+ ... |
355 |
+</abstract> |
356 |
+ |
357 |
+<comment>(Defining the several chapters)</comment> |
358 |
+</part> |
359 |
+</pre> |
360 |
+ |
361 |
+<p> |
362 |
+Each part is accompanied by a <c><title></c> and an |
363 |
+<c><abstract></c> which gives a small introduction to the part. |
364 |
+</p> |
365 |
+ |
366 |
+<p> |
367 |
+Inside each part, you define the individual <c><chapter></c>s. Each |
368 |
+chapter <e>must</e> be a separate document. As a result it is no surprise that |
369 |
+a special tag (<c><include></c>) is added to allow including the separate |
370 |
+document. |
371 |
+</p> |
372 |
+ |
373 |
+<pre caption="Defining a chapter"> |
374 |
+<chapter> |
375 |
+<title>Chapter One</title> |
376 |
+ |
377 |
+ <include href="path/to/chapter-one.xml"/> |
378 |
+ |
379 |
+</chapter> |
380 |
+</pre> |
381 |
+ |
382 |
+</body> |
383 |
+</section> |
384 |
+<section> |
385 |
+<title>Designing the Individual Chapters</title> |
386 |
+<body> |
387 |
+ |
388 |
+<p> |
389 |
+The content of an individual chapter is structured as follows: |
390 |
+</p> |
391 |
+ |
392 |
+<pre caption="Chapter Syntax"> |
393 |
+<?xml version='1.0' encoding='UTF-8'?> |
394 |
+<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
395 |
+<!-- $Header$ --> |
396 |
+ |
397 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
398 |
+<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
399 |
+ |
400 |
+<sections> |
401 |
+ |
402 |
+<abstract> |
403 |
+ This is a small explanation on chapter one. |
404 |
+</abstract> |
405 |
+ |
406 |
+<version>...</version> |
407 |
+<date>...</date> |
408 |
+ |
409 |
+<comment>(Define the several <section> and <subsection>)</comment> |
410 |
+ |
411 |
+</sections> |
412 |
+</pre> |
413 |
+ |
414 |
+<p> |
415 |
+Inside each chapter you can define <c><section></c>s (equivalent of |
416 |
+<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent |
417 |
+of <c><section></c> in a Guide). |
418 |
+</p> |
419 |
+ |
420 |
+<p> |
421 |
+Each individual chapter should have its own date and version elements. The |
422 |
+latest date of all chapters and master document will be displayed when a user |
423 |
+browses through all parts of the book. |
424 |
+</p> |
425 |
+ |
426 |
+</body> |
427 |
+</section> |
428 |
</chapter> |
429 |
|
430 |
<chapter> |
431 |
+<title>Advanced Handbook Features</title> |
432 |
+<section> |
433 |
+<title>Global Values</title> |
434 |
+<body> |
435 |
+ |
436 |
+<p> |
437 |
+Sometimes, the same values are repeated many times in several parts of a |
438 |
+handbook. Global search and replace operations tend to forget some or introduce |
439 |
+unwanted changes. Besides, it can be useful to define different values to be |
440 |
+used in shared chapters depending on which handbook includes the chapter. |
441 |
+</p> |
442 |
+ |
443 |
+<p> |
444 |
+Global values can be defined in a handbook master file and used in all included |
445 |
+chapters. |
446 |
+</p> |
447 |
+ |
448 |
+<p> |
449 |
+To define global values, add a <c><values></c> element to the handbook |
450 |
+master file. Each value is then defined in a <c><key></c> element whose |
451 |
+<c>id</c> attribute identifies the value, i.e. it is the name of your variable. |
452 |
+The content of the <c><key></c> is its value. |
453 |
+</p> |
454 |
+ |
455 |
+<p> |
456 |
+The following example defines three values in a handbook master file: |
457 |
+</p> |
458 |
+ |
459 |
+<pre caption="Define values in a handbook"> |
460 |
+<?xml version='1.0' encoding='UTF-8'?> |
461 |
+<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
462 |
+<!-- $Header$ --> |
463 |
+ |
464 |
+<book> |
465 |
+<title>Example Book Usage</title> |
466 |
+ |
467 |
+<i><values> |
468 |
+ <key id="arch">x86</key> |
469 |
+ <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> |
470 |
+ <key id="min-cd-size">57</key> |
471 |
+</values></i> |
472 |
+ |
473 |
+<author...> |
474 |
+ ... |
475 |
+</author> |
476 |
+ |
477 |
+... |
478 |
+</pre> |
479 |
+ |
480 |
+<p> |
481 |
+The defined values can then be used throughout the handbook with the in-line |
482 |
+<c><keyval id="key_id"/></c> element. Specify the name of the key in its |
483 |
+<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by |
484 |
+"install-x86-minimal-2007.0-r1.iso" in our example. |
485 |
+</p> |
486 |
+ |
487 |
+<pre caption="Using defined values"> |
488 |
+<p> |
489 |
+The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> |
490 |
+and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this |
491 |
+Installation CD to install Gentoo, but <e>only</e> with a working Internet |
492 |
+connection. |
493 |
+</p> |
494 |
+</pre> |
495 |
+ |
496 |
+<p> |
497 |
+To make life easier on our translators, only use actual values, i.e. content |
498 |
+that does not need to be translated. For instance, we defined the |
499 |
+<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. |
500 |
+</p> |
501 |
+ |
502 |
+</body> |
503 |
+</section> |
504 |
+<section> |
505 |
+<title>Conditional Elements</title> |
506 |
+<body> |
507 |
+ |
508 |
+<p> |
509 |
+Chapters that are shared by several handbooks such as our <uri |
510 |
+link="/doc/en/handbook/">Installation Handbooks</uri> often have small |
511 |
+differences depending on which handbook includes them. Instead of adding |
512 |
+content that is irrelevant to some handbooks, authors can add a condition to |
513 |
+the following elements: <c><section></c>, <c><subsection></c>, |
514 |
+<c><body></c>, <c><note></c>, <c><impo></c>, |
515 |
+<c><warn></c>, <c><pre></c>, <c><p></c>, |
516 |
+<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> |
517 |
+and <c><li></c>. |
518 |
+</p> |
519 |
+ |
520 |
+<p> |
521 |
+The condition must be an <uri |
522 |
+link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be |
523 |
+evaluated when transforming the XML. If it evaluates to <c>true</c>, the |
524 |
+element is processed, if not, it is ignored. The condition is specified in a |
525 |
+<c>test</c> attribute. |
526 |
+</p> |
527 |
+ |
528 |
+<p> |
529 |
+The following example uses the <c>arch</c> value that is defined in each |
530 |
+handbook master file to condition some content: |
531 |
+</p> |
532 |
+ |
533 |
+<pre caption="Using conditional elements"> |
534 |
+<body test="contains('AMD64 x86',func:keyval('arch'))"> |
535 |
+ |
536 |
+<p> |
537 |
+This paragraph applies to both x86 and AMD64 architectures. |
538 |
+</p> |
539 |
+ |
540 |
+<p test="func:keyval('arch')='x86'"> |
541 |
+This paragraph only applies to the x86 architecture. |
542 |
+</p> |
543 |
+ |
544 |
+<p test="func:keyval('arch')='AMD64'"> |
545 |
+This paragraph only applies to the AMD64 architecture. |
546 |
+</p> |
547 |
+ |
548 |
+<p test="func:keyval('arch')='PPC'"> |
549 |
+This paragraph will never be seen! |
550 |
+The whole body is skipped because of the first condition. |
551 |
+</p> |
552 |
+ |
553 |
+</body> |
554 |
+ |
555 |
+<body test="contains('AMD64 PPC64',func:keyval('arch'))"> |
556 |
+ |
557 |
+<p> |
558 |
+This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because |
559 |
+the 'AMD64 PPC64' string does contain 'PPC'. |
560 |
+</p> |
561 |
+ |
562 |
+<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> |
563 |
+This note only applies to the AMD64 and PPC64 architectures. |
564 |
+</note> |
565 |
+ |
566 |
+</body> |
567 |
+</pre> |
568 |
+ |
569 |
+</body> |
570 |
+</section> |
571 |
+</chapter> |
572 |
+ |
573 |
+<chapter id="codingstyle"> |
574 |
<title>Coding Style</title> |
575 |
<section> |
576 |
<title>Introduction</title> |
577 |
@@ -877,156 +1207,21 @@ |
578 |
</chapter> |
579 |
|
580 |
<chapter> |
581 |
-<title>Handbook Format</title> |
582 |
-<section> |
583 |
-<title>Guide vs Book</title> |
584 |
-<body> |
585 |
- |
586 |
-<p> |
587 |
-For high-volume documentation, such as the <uri |
588 |
-link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
589 |
-broader format was needed. We designed a GuideXML-compatible enhancement that |
590 |
-allows us to write modular and multi-page documentation. |
591 |
-</p> |
592 |
- |
593 |
-</body> |
594 |
-</section> |
595 |
-<section> |
596 |
-<title>Main File</title> |
597 |
-<body> |
598 |
- |
599 |
-<p> |
600 |
-The first change is the need for a "master" document. This document contains no |
601 |
-real content, but links to the individual documentation modules. The syntax |
602 |
-doesn't differ much from GuideXML: |
603 |
-</p> |
604 |
- |
605 |
-<pre caption="Example book usage"> |
606 |
-<?xml version='1.0' encoding='UTF-8'?> |
607 |
-<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
608 |
-<!-- $Header$ --> |
609 |
- |
610 |
-<<i>book</i> link="example.xml"> |
611 |
-<title>Example Book Usage</title> |
612 |
- |
613 |
-<author...> |
614 |
- ... |
615 |
-</author> |
616 |
- |
617 |
-<abstract> |
618 |
- ... |
619 |
-</abstract> |
620 |
- |
621 |
-<!-- The content of this document is licensed under the CC-BY-SA license --> |
622 |
-<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
623 |
-<license/> |
624 |
- |
625 |
-<version>...</version> |
626 |
-<date>...</date> |
627 |
-</pre> |
628 |
- |
629 |
-<p> |
630 |
-So far no real differences (except for the <c><book></c> instead of |
631 |
-<c><guide></c> tag). Instead of starting with the individual |
632 |
-<c><chapter></c>s, you define a <c><part></c>, which is the |
633 |
-equivalent of a separate part in a book: |
634 |
-</p> |
635 |
- |
636 |
-<pre caption="Defining a part"> |
637 |
-<part> |
638 |
-<title>Part One</title> |
639 |
-<abstract> |
640 |
- ... |
641 |
-</abstract> |
642 |
- |
643 |
-<comment>(Defining the several chapters)</comment> |
644 |
-</part> |
645 |
-</pre> |
646 |
- |
647 |
-<p> |
648 |
-Each part is accompanied by a <c><title></c> and an |
649 |
-<c><abstract></c> which gives a small introduction to the part. |
650 |
-</p> |
651 |
- |
652 |
-<p> |
653 |
-Inside each part, you define the individual <c><chapter></c>s. Each |
654 |
-chapter <e>must</e> be a separate document. As a result it is no surprise that |
655 |
-a special tag (<c><include></c>) is added to allow including the separate |
656 |
-document. |
657 |
-</p> |
658 |
- |
659 |
-<pre caption="Defining a chapter"> |
660 |
-<chapter> |
661 |
-<title>Chapter One</title> |
662 |
-<abstract> |
663 |
- This is a small explanation on chapter one. |
664 |
-</abstract> |
665 |
- |
666 |
- <include href="path/to/chapter-one.xml"/> |
667 |
- |
668 |
-</chapter> |
669 |
-</pre> |
670 |
- |
671 |
-</body> |
672 |
-</section> |
673 |
-<section> |
674 |
-<title>Designing the Individual Chapters</title> |
675 |
-<body> |
676 |
- |
677 |
-<p> |
678 |
-The content of an individual chapter is structured as follows: |
679 |
-</p> |
680 |
- |
681 |
-<pre caption="Chapter Syntax"> |
682 |
-<?xml version='1.0' encoding='UTF-8'?> |
683 |
-<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
684 |
-<!-- $Header$ --> |
685 |
- |
686 |
-<!-- The content of this document is licensed under the CC-BY-SA license --> |
687 |
-<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
688 |
- |
689 |
-<sections> |
690 |
- |
691 |
-<version>...</version> |
692 |
-<date>...</date> |
693 |
- |
694 |
-<comment>(Define the several <section> and <subsection>)</comment> |
695 |
- |
696 |
-</sections> |
697 |
-</pre> |
698 |
- |
699 |
-<p> |
700 |
-Inside each chapter you can define <c><section></c>s (equivalent of |
701 |
-<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent |
702 |
-of <c><section></c> in a Guide). |
703 |
-</p> |
704 |
- |
705 |
-<p> |
706 |
-Each individual chapter should have its own date and version elements. The |
707 |
-latest date of all chapters and master document will be displayed when a user |
708 |
-browses through all parts of the book. |
709 |
-</p> |
710 |
- |
711 |
-</body> |
712 |
-</section> |
713 |
-</chapter> |
714 |
- |
715 |
-<chapter> |
716 |
<title>Resources</title> |
717 |
<section> |
718 |
<title>Start writing</title> |
719 |
<body> |
720 |
|
721 |
<p> |
722 |
-Guide has been specially designed to be "lean and mean" so that developers can |
723 |
-spend more time writing documentation and less time learning the actual XML |
724 |
+GuideXML has been specially designed to be "lean and mean" so that developers |
725 |
+can spend more time writing documentation and less time learning the actual XML |
726 |
syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
727 |
-to start writing quality Gentoo documentation. You might be interested |
728 |
-in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation |
729 |
-Development Tips & Tricks</uri>. If you'd like to help (or have any |
730 |
-questions about guide), please post a message to the <uri |
731 |
-link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd |
732 |
-like to tackle. Have fun! |
733 |
+to start writing quality Gentoo documentation. You might be interested in our |
734 |
+<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips |
735 |
+& Tricks</uri>. If you'd like to help (or have any questions about |
736 |
+GuideXML), please post a message to the <uri |
737 |
+link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like |
738 |
+to tackle. Have fun! |
739 |
</p> |
740 |
|
741 |
</body> |
742 |
|
743 |
|
744 |
|
745 |
-- |
746 |
gentoo-doc-cvs@g.o mailing list |