1 |
cam |
1.41 |
<?xml version="1.0" encoding="UTF-8"?> |
2 |
drobbins |
1.1 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 |
swift |
1.72 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.71 2011/11/29 19:02:45 swift Exp $ --> |
4 |
drobbins |
1.1 |
|
5 |
neysx |
1.67 |
<guide> |
6 |
|
|
<title>Gentoo GuideXML Guide</title> |
7 |
swift |
1.15 |
|
8 |
|
|
<author title="Author"> |
9 |
neysx |
1.67 |
<mail link="neysx"/> |
10 |
neysx |
1.58 |
</author> |
11 |
|
|
<author title="Author"> |
12 |
swift |
1.15 |
<mail link="drobbins@gentoo.org">Daniel Robbins</mail> |
13 |
|
|
</author> |
14 |
swift |
1.19 |
<author title="Author"><!-- zhen@gentoo.org --> |
15 |
|
|
John P. Davis |
16 |
swift |
1.15 |
</author> |
17 |
|
|
<author title="Editor"> |
18 |
|
|
<mail link="peesh@gentoo.org">Jorge Paulo</mail> |
19 |
|
|
</author> |
20 |
swift |
1.25 |
<author title="Editor"> |
21 |
nightmorph |
1.66 |
<mail link="swift@gentoo.org">Sven Vermeulen</mail> |
22 |
swift |
1.25 |
</author> |
23 |
nightmorph |
1.69 |
<author title="Editor"> |
24 |
|
|
<mail link="nightmorph"/> |
25 |
|
|
</author> |
26 |
drobbins |
1.1 |
|
27 |
swift |
1.15 |
<abstract> |
28 |
|
|
This guide shows you how to compose web documentation using the new lightweight |
29 |
vapier |
1.50 |
Gentoo GuideXML syntax. This syntax is the official format for Gentoo |
30 |
swift |
1.15 |
documentation, and this document itself was created using GuideXML. This guide |
31 |
|
|
assumes a basic working knowledge of XML and HTML. |
32 |
drobbins |
1.1 |
</abstract> |
33 |
|
|
|
34 |
swift |
1.31 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
35 |
swift |
1.46 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
36 |
swift |
1.26 |
<license/> |
37 |
|
|
|
38 |
swift |
1.72 |
<version>13</version> |
39 |
|
|
<date>2012-10-07</date> |
40 |
drobbins |
1.1 |
|
41 |
|
|
<chapter> |
42 |
neysx |
1.67 |
<title>GuideXML basics</title> |
43 |
drobbins |
1.1 |
<section> |
44 |
neysx |
1.67 |
<title>GuideXML design goals</title> |
45 |
drobbins |
1.1 |
<body> |
46 |
|
|
|
47 |
swift |
1.15 |
<p> |
48 |
neysx |
1.67 |
The guideXML syntax is lightweight yet expressive, so that it is easy to |
49 |
drobbins |
1.1 |
learn yet also provides all the features we need for the creation of web |
50 |
|
|
documentation. The number of tags is kept to a minimum -- just those we need. |
51 |
|
|
This makes it easy to transform guide into other formats, such as DocBook |
52 |
swift |
1.15 |
XML/SGML or web-ready HTML. |
53 |
|
|
</p> |
54 |
drobbins |
1.1 |
|
55 |
swift |
1.15 |
<p> |
56 |
neysx |
1.67 |
The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML |
57 |
swift |
1.15 |
documents. |
58 |
|
|
</p> |
59 |
drobbins |
1.1 |
|
60 |
|
|
</body> |
61 |
|
|
</section> |
62 |
|
|
<section> |
63 |
swift |
1.20 |
<title>Further Resources</title> |
64 |
drobbins |
1.1 |
<body> |
65 |
|
|
|
66 |
swift |
1.15 |
<p> |
67 |
neysx |
1.34 |
If you are planning on contributing documentation to Gentoo, or you want to |
68 |
neysx |
1.52 |
test GuideXML, please read our <uri |
69 |
|
|
link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide |
70 |
|
|
which contains tips and tricks for documentation development. |
71 |
|
|
</p> |
72 |
|
|
|
73 |
|
|
<p> |
74 |
|
|
You may want to look at the <uri link="?passthru=1">XML source</uri> of this |
75 |
|
|
document while you read it. |
76 |
drobbins |
1.1 |
</p> |
77 |
|
|
|
78 |
|
|
</body> |
79 |
|
|
</section> |
80 |
|
|
</chapter> |
81 |
swift |
1.15 |
|
82 |
drobbins |
1.1 |
<chapter> |
83 |
neysx |
1.67 |
<title>GuideXML</title> |
84 |
drobbins |
1.1 |
<section> |
85 |
|
|
<title>Basic structure</title> |
86 |
|
|
<body> |
87 |
|
|
|
88 |
swift |
1.15 |
<p> |
89 |
swift |
1.36 |
Let's start learning the GuideXML syntax. We'll start with the the initial |
90 |
|
|
tags used in a GuideXML document: |
91 |
swift |
1.15 |
</p> |
92 |
drobbins |
1.1 |
|
93 |
|
|
<pre caption="The initial part of a guide XML document"> |
94 |
cam |
1.41 |
<?xml version="1.0" encoding="UTF-8"?> |
95 |
swift |
1.25 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
96 |
neysx |
1.42 |
<!-- $Header$ --> |
97 |
|
|
|
98 |
swift |
1.72 |
<guide lang="<i>en</i>"> |
99 |
vapier |
1.50 |
<title><i>Gentoo Documentation Guide</i></title> |
100 |
neysx |
1.49 |
|
101 |
swift |
1.33 |
<author title="<i>Author</i>"> |
102 |
|
|
<mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail> |
103 |
drobbins |
1.1 |
</author> |
104 |
|
|
|
105 |
swift |
1.15 |
<abstract> |
106 |
|
|
<i>This guide shows you how to compose web documentation using |
107 |
|
|
our new lightweight Gentoo GuideXML syntax. This syntax is the official |
108 |
vapier |
1.50 |
format for Gentoo web documentation, and this document itself was created |
109 |
swift |
1.15 |
using GuideXML.</i> |
110 |
|
|
</abstract> |
111 |
drobbins |
1.1 |
|
112 |
swift |
1.27 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
113 |
swift |
1.71 |
<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
114 |
|
|
<license version="3.0"/> |
115 |
swift |
1.14 |
|
116 |
nightmorph |
1.70 |
<version><i>1</i></version> |
117 |
swift |
1.71 |
<date><i>2011-11-29</i></date> |
118 |
drobbins |
1.1 |
</pre> |
119 |
|
|
|
120 |
swift |
1.15 |
<p> |
121 |
neysx |
1.42 |
On the first lines, we see the requisite tag that identifies this as an XML |
122 |
|
|
document and specifies its DTD. The <c><!-- $Header$ --></c> line |
123 |
|
|
will be automatically modified by the CVS server and helps to track revisions. |
124 |
neysx |
1.51 |
Next, there's a <c><guide></c> tag -- the entire guide document is |
125 |
neysx |
1.67 |
enclosed within a <c><guide> </guide></c> pair. |
126 |
|
|
<br/> |
127 |
|
|
The <c>lang</c> attribute should be used to specify the language code of your |
128 |
|
|
document. It is used to format the date and insert strings like "<e>Note</e>", |
129 |
|
|
"<e>Content</e>", etc. in the specified language. The default is English. |
130 |
neysx |
1.35 |
</p> |
131 |
|
|
|
132 |
|
|
<p> |
133 |
drobbins |
1.1 |
Next, there's a <c><title></c> tag, used to set the title for the entire |
134 |
swift |
1.15 |
guide document. |
135 |
|
|
</p> |
136 |
drobbins |
1.1 |
|
137 |
swift |
1.15 |
<p> |
138 |
|
|
Then, we come to the <c><author></c> tags, which contain information |
139 |
drobbins |
1.1 |
about the various authors of the document. Each <c><author></c> tag |
140 |
neysx |
1.52 |
allows for an optional <c>title</c> element, used to specify the author's |
141 |
drobbins |
1.1 |
relationship to the document (author, co-author, editor, etc.). In this |
142 |
|
|
particular example, the authors' names are enclosed in another tag -- a |
143 |
|
|
<c><mail></c> tag, used to specify an email address for this particular |
144 |
neysx |
1.67 |
person. The <c><mail></c> tag is optional and can be omitted, and at |
145 |
|
|
least one <c><author></c> element is required per guide document. |
146 |
drobbins |
1.1 |
</p> |
147 |
|
|
|
148 |
swift |
1.15 |
<p> |
149 |
|
|
Next, we come to the <c><abstract></c>, <c><version></c> and |
150 |
drobbins |
1.1 |
<c><date></c> tags, used to specify a summary of the document, the |
151 |
neysx |
1.35 |
current version number, and the current version date (in YYYY-MM-DD format) |
152 |
|
|
respectively. Dates that are invalid or not in the YYYY-MM-DD format will |
153 |
|
|
appear verbatim in the rendered document. |
154 |
|
|
</p> |
155 |
|
|
|
156 |
|
|
<p> |
157 |
neysx |
1.67 |
This sums up the tags that should appear at the beginning of a guide document. |
158 |
|
|
Besides the <c><title></c> and <c><mail></c> tags, these tags |
159 |
|
|
shouldn't appear anywhere else except immediately inside the |
160 |
drobbins |
1.1 |
<c><guide></c> tag, and for consistency it's recommended (but not |
161 |
swift |
1.15 |
required) that these tags appear before the content of the document. |
162 |
|
|
</p> |
163 |
swift |
1.14 |
|
164 |
swift |
1.15 |
<p> |
165 |
swift |
1.71 |
Finally we have the <c><license version="3.0"/></c> tag, used to publish |
166 |
|
|
the document under the <uri link="http://creativecommons.org/licenses/by-sa/3.0/">Creative |
167 |
neysx |
1.38 |
Commons - Attribution / Share Alike</uri> license as required by the <uri |
168 |
swift |
1.71 |
link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. Historically, |
169 |
|
|
the tag <c><license /></c> was used, which denoted the 2.5 version of the |
170 |
|
|
license. This is still accepted/allowed. |
171 |
swift |
1.15 |
</p> |
172 |
drobbins |
1.1 |
|
173 |
|
|
</body> |
174 |
|
|
</section> |
175 |
|
|
<section> |
176 |
|
|
<title>Chapters and sections</title> |
177 |
|
|
<body> |
178 |
swift |
1.15 |
|
179 |
|
|
<p> |
180 |
neysx |
1.37 |
Once the initial tags have been specified, you're ready to start adding the |
181 |
|
|
structural elements of the document. Guide documents are divided into |
182 |
|
|
chapters, and each chapter can hold one or more sections. Every chapter and |
183 |
|
|
section has a title. Here's an example chapter with a single section, |
184 |
|
|
consisting of a paragraph. If you append this XML to the XML in the <uri |
185 |
|
|
link="#doc_chap2_pre1">previous excerpt</uri> and append a |
186 |
|
|
<c></guide></c> to the end of the file, you'll have a valid (if minimal) |
187 |
|
|
guide document: |
188 |
drobbins |
1.1 |
</p> |
189 |
|
|
|
190 |
neysx |
1.37 |
<pre caption="Minimal guide example"> |
191 |
drobbins |
1.1 |
<chapter> |
192 |
|
|
<title><i>This is my chapter</i></title> |
193 |
|
|
<section> |
194 |
swift |
1.15 |
<title><i>This is section one of my chapter</i></title> |
195 |
|
|
<body> |
196 |
|
|
|
197 |
|
|
<p> |
198 |
|
|
<i>This is the actual text content of my section.</i> |
199 |
|
|
</p> |
200 |
|
|
|
201 |
|
|
</body> |
202 |
drobbins |
1.1 |
</section> |
203 |
|
|
</chapter> |
204 |
|
|
</pre> |
205 |
|
|
|
206 |
swift |
1.15 |
<p> |
207 |
|
|
Above, I set the chapter title by adding a child <c><title></c> |
208 |
drobbins |
1.1 |
element to the <c><chapter></c> element. Then, I created a section by |
209 |
|
|
adding a <c><section></c> element. If you look inside the |
210 |
|
|
<c><section></c> element, you'll see that it has two child elements -- a |
211 |
|
|
<c><title></c> and a <c><body></c>. While the <c><title></c> |
212 |
|
|
is nothing new, the <c><body></c> is -- it contains the actual text |
213 |
|
|
content of this particular section. We'll look at the tags that are allowed |
214 |
swift |
1.15 |
inside a <c><body></c> element in a bit. |
215 |
|
|
</p> |
216 |
drobbins |
1.1 |
|
217 |
swift |
1.15 |
<note> |
218 |
neysx |
1.67 |
A <c><guide></c> element must contain at least one <c><chapter></c> |
219 |
|
|
elements, a <c><chapter></c> must contain at least one |
220 |
|
|
<c><section></c> elements and a <c><section></c> element must |
221 |
|
|
contain at least one <c><body></c> element. |
222 |
swift |
1.15 |
</note> |
223 |
drobbins |
1.1 |
|
224 |
|
|
</body> |
225 |
|
|
</section> |
226 |
|
|
<section> |
227 |
|
|
<title>An example <body></title> |
228 |
|
|
<body> |
229 |
swift |
1.15 |
|
230 |
drobbins |
1.1 |
<p> |
231 |
neysx |
1.37 |
Now, it's time to learn how to mark up actual content. Here's the XML code for |
232 |
|
|
an example <c><body></c> element: |
233 |
drobbins |
1.1 |
</p> |
234 |
swift |
1.15 |
|
235 |
neysx |
1.37 |
<pre caption="Example of a body element"> |
236 |
drobbins |
1.1 |
<p> |
237 |
|
|
This is a paragraph. <path>/etc/passwd</path> is a file. |
238 |
neysx |
1.35 |
<uri>http://forums.gentoo.org</uri> is my favorite website. |
239 |
drobbins |
1.1 |
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
240 |
|
|
</p> |
241 |
|
|
|
242 |
neysx |
1.37 |
<pre caption="Code Sample"> |
243 |
drobbins |
1.1 |
This is text output or code. |
244 |
|
|
# <i>this is user input</i> |
245 |
|
|
|
246 |
|
|
Make HTML/XML easier to read by using selective emphasis: |
247 |
|
|
<foo><i>bar</i></foo> |
248 |
|
|
|
249 |
neysx |
1.58 |
<comment>(This is how to insert a comment into a code block)</comment> |
250 |
drobbins |
1.1 |
</pre> |
251 |
swift |
1.15 |
|
252 |
|
|
<note> |
253 |
|
|
This is a note. |
254 |
|
|
</note> |
255 |
|
|
|
256 |
|
|
<warn> |
257 |
|
|
This is a warning. |
258 |
|
|
</warn> |
259 |
|
|
|
260 |
|
|
<impo> |
261 |
|
|
This is important. |
262 |
|
|
</impo> |
263 |
drobbins |
1.1 |
</pre> |
264 |
swift |
1.15 |
|
265 |
|
|
<p> |
266 |
neysx |
1.37 |
Now, here's how the <c><body></c> element above is rendered: |
267 |
swift |
1.15 |
</p> |
268 |
drobbins |
1.1 |
|
269 |
|
|
<p> |
270 |
|
|
This is a paragraph. <path>/etc/passwd</path> is a file. |
271 |
swift |
1.45 |
<uri>http://forums.gentoo.org</uri> is my favorite web site. |
272 |
drobbins |
1.1 |
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
273 |
|
|
</p> |
274 |
|
|
|
275 |
neysx |
1.37 |
<pre caption="Code Sample"> |
276 |
drobbins |
1.1 |
This is text output or code. |
277 |
|
|
# <i>this is user input</i> |
278 |
|
|
|
279 |
|
|
Make HTML/XML easier to read by using selective emphasis: |
280 |
|
|
<foo><i>bar</i></foo> |
281 |
|
|
|
282 |
neysx |
1.58 |
<comment>(This is how to insert a comment into a code block)</comment> |
283 |
drobbins |
1.1 |
</pre> |
284 |
swift |
1.15 |
|
285 |
|
|
<note> |
286 |
|
|
This is a note. |
287 |
|
|
</note> |
288 |
|
|
|
289 |
|
|
<warn> |
290 |
|
|
This is a warning. |
291 |
|
|
</warn> |
292 |
|
|
|
293 |
|
|
<impo> |
294 |
|
|
This is important. |
295 |
|
|
</impo> |
296 |
|
|
|
297 |
drobbins |
1.1 |
</body> |
298 |
|
|
</section> |
299 |
|
|
<section> |
300 |
|
|
<title>The <body> tags</title> |
301 |
|
|
<body> |
302 |
|
|
|
303 |
swift |
1.15 |
<p> |
304 |
neysx |
1.52 |
We introduced a lot of new tags in the previous section -- here's what you need |
305 |
|
|
to know. The <c><p></c> (paragraph), <c><pre></c> (code block), |
306 |
|
|
<c><note></c>, <c><warn></c> (warning) and <c><impo></c> |
307 |
|
|
(important) tags all can contain one or more lines of text. Besides the |
308 |
|
|
<c><table></c>, <c><ul></c>, <c><ol></c> and |
309 |
|
|
<c><dl></c> elements (which we'll cover in just a bit), these are the |
310 |
|
|
only tags that should appear immediately inside a <c><body></c> element. |
311 |
|
|
Another thing -- these tags <e>should not</e> be stacked -- in other words, |
312 |
|
|
don't put a <c><note></c> element inside a <c><p></c> element. As |
313 |
|
|
you might guess, the <c><pre></c> element preserves its whitespace |
314 |
|
|
exactly, making it well-suited for code excerpts. You must name the |
315 |
neysx |
1.53 |
<c><pre></c> tag with a <c>caption</c> attribute: |
316 |
swift |
1.15 |
</p> |
317 |
swift |
1.12 |
|
318 |
neysx |
1.37 |
<pre caption="Named <pre>"> |
319 |
neysx |
1.51 |
<pre caption="Output of uptime"> |
320 |
swift |
1.12 |
# <i>uptime</i> |
321 |
|
|
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
322 |
|
|
</pre> |
323 |
|
|
</pre> |
324 |
drobbins |
1.1 |
|
325 |
|
|
</body> |
326 |
|
|
</section> |
327 |
|
|
<section> |
328 |
neysx |
1.52 |
<title>Epigraphs</title> |
329 |
|
|
<body> |
330 |
|
|
|
331 |
|
|
<p by="Anonymous student"> |
332 |
|
|
Delegates from the original 13 states formed the Contented Congress. Thomas |
333 |
|
|
Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration |
334 |
|
|
of Independence. Franklin discovered electricity by rubbing two cats backwards |
335 |
|
|
and declared, "A horse divided against itself cannot stand." Franklin died in |
336 |
|
|
1790 and is still dead. |
337 |
|
|
</p> |
338 |
|
|
|
339 |
|
|
<p> |
340 |
|
|
Epigraphs are sometimes used at the beginning of chapters to illustrate what is |
341 |
|
|
to follow. It is simply a paragraph with a <c>by</c> attribute that contains |
342 |
|
|
the signature. |
343 |
|
|
</p> |
344 |
|
|
|
345 |
|
|
<pre caption="Short epigraph"> |
346 |
|
|
<p by="Anonymous student"> |
347 |
|
|
Delegates from the original 13 states formed the... |
348 |
|
|
</p> |
349 |
|
|
</pre> |
350 |
|
|
|
351 |
|
|
</body> |
352 |
|
|
</section> |
353 |
|
|
<section> |
354 |
|
|
<title> |
355 |
neysx |
1.58 |
<path>, <c>, <b>, <e>, <sub> and <sup> |
356 |
neysx |
1.52 |
</title> |
357 |
drobbins |
1.1 |
<body> |
358 |
|
|
|
359 |
swift |
1.15 |
<p> |
360 |
neysx |
1.52 |
The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, |
361 |
|
|
<c><sub></c> and <c><sup></c> elements can be used inside any child |
362 |
neysx |
1.58 |
<c><body></c> tag, except for <c><pre></c>. |
363 |
swift |
1.15 |
</p> |
364 |
drobbins |
1.1 |
|
365 |
swift |
1.15 |
<p> |
366 |
|
|
The <c><path></c> element is used to mark text that refers to an |
367 |
|
|
<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
368 |
swift |
1.45 |
<e>simple filename</e>. This element is generally rendered with a mono spaced |
369 |
swift |
1.15 |
font to offset it from the standard paragraph type. |
370 |
|
|
</p> |
371 |
drobbins |
1.1 |
|
372 |
swift |
1.15 |
<p> |
373 |
|
|
The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
374 |
drobbins |
1.1 |
input</e>. Think of <c><c></c> as a way to alert the reader to something |
375 |
|
|
that they can type in that will perform some kind of action. For example, all |
376 |
|
|
the XML tags displayed in this document are enclosed in a <c><c></c> |
377 |
|
|
element because they represent something that the user could type in that is |
378 |
|
|
not a path. By using <c><c></c> elements, you'll help your readers |
379 |
|
|
quickly identify commands that they need to type in. Also, because |
380 |
|
|
<c><c></c> elements are already offset from regular text, <e>it is rarely |
381 |
|
|
necessary to surround user input with double-quotes</e>. For example, don't |
382 |
|
|
refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
383 |
swift |
1.15 |
the use of unnecessary double-quotes makes a document more readable -- and |
384 |
|
|
adorable! |
385 |
|
|
</p> |
386 |
drobbins |
1.1 |
|
387 |
swift |
1.15 |
<p> |
388 |
neysx |
1.51 |
As you might have guessed, <c><b></c> is used to <b>boldface</b> some |
389 |
|
|
text. |
390 |
|
|
</p> |
391 |
|
|
|
392 |
|
|
<p> |
393 |
swift |
1.15 |
<c><e></c> is used to apply emphasis to a word or phrase; for example: |
394 |
drobbins |
1.1 |
I <e>really</e> should use semicolons more often. As you can see, this text is |
395 |
|
|
offset from the regular paragraph type for emphasis. This helps to give your |
396 |
swift |
1.15 |
prose more <e>punch</e>! |
397 |
|
|
</p> |
398 |
drobbins |
1.1 |
|
399 |
neysx |
1.52 |
<p> |
400 |
|
|
The <c><sub></c> and <c><sup></c> elements are used to specify |
401 |
|
|
<sub>subscript</sub> and <sup>superscript</sup>. |
402 |
|
|
</p> |
403 |
|
|
|
404 |
drobbins |
1.1 |
</body> |
405 |
|
|
</section> |
406 |
|
|
<section> |
407 |
neysx |
1.58 |
<title>Code samples and colour-coding</title> |
408 |
|
|
<body> |
409 |
|
|
|
410 |
|
|
<p> |
411 |
|
|
To improve the readability of code samples, the following tags are allowed |
412 |
|
|
inside <c><pre></c> blocks: |
413 |
|
|
</p> |
414 |
|
|
|
415 |
|
|
<dl> |
416 |
|
|
<dt><c><i></c></dt> |
417 |
|
|
<dd>Distinguishes user input from displayed text</dd> |
418 |
|
|
<dt><c><comment></c></dt> |
419 |
|
|
<dd>Comments relevant to the action(s) that appear after the comment</dd> |
420 |
|
|
<dt><c><keyword></c></dt> |
421 |
|
|
<dd>Denotes a keyword in the language used in the code sample |
422 |
|
|
</dd> |
423 |
|
|
<dt><c><ident></c></dt> |
424 |
|
|
<dd>Used for an identifier |
425 |
|
|
</dd> |
426 |
|
|
<dt><c><const></c></dt> |
427 |
|
|
<dd>Used for a constant |
428 |
|
|
</dd> |
429 |
|
|
<dt><c><stmt></c></dt> |
430 |
|
|
<dd>Used for a statement |
431 |
|
|
</dd> |
432 |
|
|
<dt><c><var></c></dt> |
433 |
|
|
<dd>Used for a variable |
434 |
|
|
</dd> |
435 |
|
|
</dl> |
436 |
|
|
|
437 |
|
|
<note> |
438 |
|
|
Remember that all leading and trailing spaces, and line breaks in |
439 |
|
|
<c><pre></c> blocks will appear in the displayed html page. |
440 |
|
|
</note> |
441 |
|
|
|
442 |
|
|
<p> |
443 |
|
|
Sample colour-coded <c><pre></c> block: |
444 |
|
|
</p> |
445 |
|
|
|
446 |
|
|
<pre caption="My first ebuild"> |
447 |
nightmorph |
1.69 |
<comment># Copyright 1999-2009 <b>Gentoo Foundation</b> |
448 |
neysx |
1.58 |
# Distributed under the terms of the GNU General Public License v2 |
449 |
|
|
# $Header: $</comment> |
450 |
|
|
|
451 |
|
|
<ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const> |
452 |
|
|
<ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const> |
453 |
|
|
<ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const> |
454 |
|
|
|
455 |
|
|
<ident>LICENSE</ident>=<const>"GPL-2"</const> |
456 |
|
|
<ident>SLOT</ident>=<const>"0"</const> |
457 |
|
|
<ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const> |
458 |
|
|
<ident>IUSE</ident>=<const>""</const> |
459 |
|
|
|
460 |
|
|
<stmt>src_compile()</stmt> { |
461 |
nightmorph |
1.69 |
<keyword>econf</keyword> --with-posix-regex |
462 |
neysx |
1.58 |
<keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const> |
463 |
|
|
} |
464 |
|
|
|
465 |
|
|
<stmt>src_install()</stmt> { |
466 |
|
|
<keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const> |
467 |
|
|
|
468 |
|
|
<keyword>dodoc</keyword> FAQ NEWS README |
469 |
|
|
<keyword>dohtml</keyword> EXTENDING.html ctags.html |
470 |
|
|
} |
471 |
|
|
</pre> |
472 |
|
|
|
473 |
|
|
</body> |
474 |
|
|
</section> |
475 |
|
|
<section> |
476 |
drobbins |
1.1 |
<title><mail> and <uri></title> |
477 |
|
|
<body> |
478 |
|
|
|
479 |
swift |
1.15 |
<p> |
480 |
neysx |
1.51 |
We've taken a look at the <c><mail></c> tag earlier; it's used to link |
481 |
|
|
some text with a particular email address, and takes the form <c><mail |
482 |
neysx |
1.67 |
link="foo.bar@example.com">Mr. Foo Bar</mail></c>. If you want to display the |
483 |
|
|
email address, you can use <c><mail>foo.bar@example.com</mail></c>, this |
484 |
|
|
would be displayed as <mail>foo.bar@example.com</mail>. |
485 |
|
|
</p> |
486 |
|
|
|
487 |
|
|
<p> |
488 |
|
|
Shorter forms make it easier to use names and emails of Gentoo developers. Both |
489 |
|
|
<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c> |
490 |
|
|
would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email |
491 |
|
|
with a different content than his full name, use the second form with some |
492 |
|
|
content. For instance, use a dev's first name: <c><mail |
493 |
|
|
link="neysx">Xavier</mail></c> appears as <mail |
494 |
|
|
link="neysx">Xavier</mail>. |
495 |
|
|
<br/> |
496 |
|
|
This is particularly useful when you want to name a developer whose name |
497 |
|
|
contains "funny" characters that you can't type. |
498 |
swift |
1.15 |
</p> |
499 |
drobbins |
1.1 |
|
500 |
swift |
1.15 |
<p> |
501 |
neysx |
1.35 |
The <c><uri></c> tag is used to point to files/locations on the Internet. |
502 |
|
|
It has two forms -- the first can be used when you want to have the actual URI |
503 |
|
|
displayed in the body text, such as this link to |
504 |
neysx |
1.67 |
<uri>http://forums.gentoo.org/</uri>. To create this link, I typed |
505 |
|
|
<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is |
506 |
drobbins |
1.1 |
when you want to associate a URI with some other text -- for example, <uri |
507 |
neysx |
1.67 |
link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create |
508 |
|
|
<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the |
509 |
|
|
Gentoo Forums</uri></c>. You don't need to write |
510 |
|
|
<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site. |
511 |
|
|
For instance, a link to the <uri link="/doc/en/">documentation main index</uri> |
512 |
|
|
should be simply <c><uri link="/doc/en/index.xml">documentation main |
513 |
|
|
index</uri></c>. You can even omit <c>index.xml</c> when you link to a |
514 |
|
|
directory index, e.g. <c><uri link="/doc/en/">documentation main |
515 |
|
|
index</uri></c>. Leaving the trailing slash saves an extra HTTP request. |
516 |
|
|
</p> |
517 |
|
|
|
518 |
|
|
<p> |
519 |
|
|
You should not use a <c><uri></c> tag with a <c>link</c> attribute that |
520 |
|
|
starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag. |
521 |
|
|
</p> |
522 |
|
|
|
523 |
|
|
<p> |
524 |
|
|
Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here |
525 |
|
|
syndrome</uri> as recommended by the <uri |
526 |
|
|
link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>. |
527 |
drobbins |
1.1 |
</p> |
528 |
|
|
|
529 |
|
|
</body> |
530 |
|
|
</section> |
531 |
|
|
<section> |
532 |
|
|
<title>Figures</title> |
533 |
|
|
<body> |
534 |
|
|
|
535 |
swift |
1.15 |
<p> |
536 |
|
|
Here's how to insert a figure into a document -- <c><figure |
537 |
drobbins |
1.1 |
link="mygfx.png" short="my picture" caption="my favorite picture of all |
538 |
neysx |
1.52 |
time"/></c>. The <c>link</c> attribute points to the actual graphic image, |
539 |
|
|
the <c>short</c> attribute specifies a short description (currently used for |
540 |
|
|
the image's HTML <c>alt</c> attribute), and a caption. Not too difficult |
541 |
drobbins |
1.1 |
:) We also support the standard HTML-style <img src="foo.gif"/> tag |
542 |
swift |
1.15 |
for adding images without captions, borders, etc. |
543 |
|
|
</p> |
544 |
drobbins |
1.1 |
|
545 |
|
|
</body> |
546 |
|
|
</section> |
547 |
|
|
<section> |
548 |
neysx |
1.52 |
<title>Tables</title> |
549 |
drobbins |
1.1 |
<body> |
550 |
|
|
|
551 |
swift |
1.15 |
<p> |
552 |
neysx |
1.67 |
GuideXML supports a simplified table syntax similar to that of HTML. To start a |
553 |
neysx |
1.51 |
table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
554 |
neysx |
1.67 |
tag. However, for inserting actual table data, we <e>don't</e> support the HTML |
555 |
|
|
<td> tag; instead, use the <c><th></c> if you are inserting a |
556 |
drobbins |
1.1 |
header, and <c><ti></c> if you are inserting a normal informational |
557 |
neysx |
1.51 |
block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
558 |
|
|
-- there's no requirement that <c><th></c> elements appear only in the |
559 |
|
|
first row. |
560 |
drobbins |
1.1 |
</p> |
561 |
|
|
|
562 |
swift |
1.15 |
<p> |
563 |
neysx |
1.60 |
Besides, both table headers (<c><th></c>) and table items |
564 |
|
|
(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to |
565 |
neysx |
1.61 |
span their content across rows, columns or both. |
566 |
|
|
</p> |
567 |
|
|
|
568 |
|
|
<p> |
569 |
neysx |
1.68 |
Furthermore, table cells (<c><ti></c> & <c><th></c>) can be |
570 |
|
|
right-aligned, left-aligned or centered with the <c>align</c> attribute. |
571 |
neysx |
1.52 |
</p> |
572 |
|
|
|
573 |
|
|
<table> |
574 |
|
|
<tr> |
575 |
neysx |
1.68 |
<th align="center" colspan="4">This title spans 4 columns</th> |
576 |
neysx |
1.52 |
</tr> |
577 |
|
|
<tr> |
578 |
neysx |
1.59 |
<th rowspan="6">This title spans 6 rows</th> |
579 |
neysx |
1.52 |
<ti>Item A1</ti> |
580 |
|
|
<ti>Item A2</ti> |
581 |
|
|
<ti>Item A3</ti> |
582 |
|
|
</tr> |
583 |
|
|
<tr> |
584 |
neysx |
1.61 |
<ti align="center">Item B1</ti> |
585 |
neysx |
1.68 |
<th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th> |
586 |
neysx |
1.52 |
</tr> |
587 |
|
|
<tr> |
588 |
neysx |
1.61 |
<ti align="right">Item C1</ti> |
589 |
neysx |
1.52 |
</tr> |
590 |
neysx |
1.59 |
<tr> |
591 |
neysx |
1.61 |
<ti colspan="3" align="center">Item D1..D3</ti> |
592 |
neysx |
1.59 |
</tr> |
593 |
|
|
<tr> |
594 |
|
|
<ti rowspan="2">Item E1..F1</ti> |
595 |
neysx |
1.61 |
<ti colspan="2" align="right">Item E2..E3</ti> |
596 |
neysx |
1.59 |
</tr> |
597 |
|
|
<tr> |
598 |
neysx |
1.61 |
<ti colspan="2" align="right">Item F2..F3</ti> |
599 |
neysx |
1.59 |
</tr> |
600 |
neysx |
1.52 |
</table> |
601 |
|
|
|
602 |
|
|
</body> |
603 |
|
|
</section> |
604 |
|
|
<section> |
605 |
|
|
<title>Lists</title> |
606 |
|
|
<body> |
607 |
|
|
|
608 |
|
|
<p> |
609 |
swift |
1.39 |
To create ordered or unordered lists, simply use the XHTML-style |
610 |
neysx |
1.52 |
<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only |
611 |
|
|
appear inside the <c><body></c> and <c><li></c> tags which means |
612 |
|
|
that you can have lists inside lists. Don't forget that you are writing XML and |
613 |
|
|
that you must close all tags including list items unlike in HTML. |
614 |
swift |
1.15 |
</p> |
615 |
drobbins |
1.1 |
|
616 |
neysx |
1.52 |
<p> |
617 |
|
|
Definition lists (<c><dl></c>) are also supported. Please note that |
618 |
|
|
neither the definition term tag (<c><dt></c>) nor the definition data tag |
619 |
|
|
(<c><dd></c>) accept any other block level tag such as paragraphs or |
620 |
neysx |
1.53 |
admonitions. A definition list comprises: |
621 |
neysx |
1.52 |
</p> |
622 |
|
|
|
623 |
|
|
<dl> |
624 |
|
|
<dt><c><dl></c></dt> |
625 |
|
|
<dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> |
626 |
|
|
<dt><c><dt></c></dt> |
627 |
|
|
<dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> |
628 |
|
|
<dt><c><dd></c></dt> |
629 |
|
|
<dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> |
630 |
|
|
</dl> |
631 |
|
|
|
632 |
|
|
<p> |
633 |
|
|
The following list copied from <uri |
634 |
|
|
link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows |
635 |
|
|
that a definition list can contain ordered and unordered lists. It may not |
636 |
|
|
contain another definition list though. |
637 |
|
|
</p> |
638 |
|
|
|
639 |
|
|
<dl> |
640 |
|
|
<dt><b>The ingredients:</b></dt> |
641 |
|
|
<dd> |
642 |
|
|
<ul> |
643 |
|
|
<li>100 g. flour</li> |
644 |
|
|
<li>10 g. sugar</li> |
645 |
|
|
<li>1 cup water</li> |
646 |
|
|
<li>2 eggs</li> |
647 |
|
|
<li>salt, pepper</li> |
648 |
|
|
</ul> |
649 |
|
|
</dd> |
650 |
|
|
<dt><b>The procedure:</b></dt> |
651 |
|
|
<dd> |
652 |
|
|
<ol> |
653 |
neysx |
1.53 |
<li>Mix dry ingredients thoroughly</li> |
654 |
|
|
<li>Pour in wet ingredients</li> |
655 |
|
|
<li>Mix for 10 minutes</li> |
656 |
|
|
<li>Bake for one hour at 300 degrees</li> |
657 |
neysx |
1.52 |
</ol> |
658 |
|
|
</dd> |
659 |
|
|
<dt><b>Notes:</b></dt> |
660 |
neysx |
1.53 |
<dd>The recipe may be improved by adding raisins</dd> |
661 |
neysx |
1.52 |
</dl> |
662 |
|
|
|
663 |
drobbins |
1.1 |
</body> |
664 |
|
|
</section> |
665 |
|
|
<section> |
666 |
|
|
<title>Intra-document references</title> |
667 |
|
|
<body> |
668 |
|
|
|
669 |
swift |
1.15 |
<p> |
670 |
neysx |
1.67 |
GuideXML makes it really easy to reference other parts of the document using |
671 |
drobbins |
1.1 |
hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
672 |
|
|
One</uri> by typing <c><uri link="#doc_chap1">Chapter |
673 |
|
|
One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
674 |
|
|
Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
675 |
neysx |
1.67 |
Chapter One</uri></c>. To refer to figure 3 in chapter 1, type |
676 |
|
|
<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer |
677 |
|
|
to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type |
678 |
|
|
<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>. |
679 |
swift |
1.17 |
</p> |
680 |
swift |
1.23 |
|
681 |
|
|
<p> |
682 |
|
|
However, some guides change often and using such "counting" can lead to broken |
683 |
|
|
links. In order to cope with this, you can define a name for a |
684 |
neysx |
1.47 |
<c><chapter></c>, <c><section></c> or a <c><tr></c> by using |
685 |
|
|
the <c>id</c> attribute, and then point to that attribute, like this: |
686 |
swift |
1.23 |
</p> |
687 |
|
|
|
688 |
|
|
<pre caption="Using the id attribute"> |
689 |
|
|
<chapter id="foo"> |
690 |
|
|
<title>This is foo!</title> |
691 |
|
|
... |
692 |
|
|
<p> |
693 |
|
|
More information can be found in the <uri link="#foo">foo chapter</uri> |
694 |
|
|
</p> |
695 |
|
|
</pre> |
696 |
swift |
1.17 |
|
697 |
|
|
</body> |
698 |
|
|
</section> |
699 |
neysx |
1.51 |
<section> |
700 |
|
|
<title>Disclaimers and obsolete documents</title> |
701 |
|
|
<body> |
702 |
|
|
|
703 |
|
|
<p> |
704 |
alin |
1.54 |
A <c>disclaimer</c> attribute can be applied to guides and handbooks to display |
705 |
|
|
a predefined disclaimer at the top of the document. The available disclaimers |
706 |
|
|
are: |
707 |
neysx |
1.51 |
</p> |
708 |
|
|
|
709 |
|
|
<ul> |
710 |
|
|
<li> |
711 |
|
|
<b>articles</b> is used for <uri link="/doc/en/articles/">republished |
712 |
|
|
articles</uri> |
713 |
|
|
</li> |
714 |
|
|
<li> |
715 |
|
|
<b>draft</b> is used to indicate a document is still being worked on and |
716 |
|
|
should not be considered official |
717 |
|
|
</li> |
718 |
|
|
<li> |
719 |
|
|
<b>oldbook</b> is used on old handbooks to indicate they are not maintained |
720 |
|
|
anymore |
721 |
|
|
</li> |
722 |
|
|
<li><b>obsolete</b> is used to mark a document as obsolete.</li> |
723 |
|
|
</ul> |
724 |
|
|
|
725 |
|
|
<p> |
726 |
|
|
When marking a document as obsolete, you might want to add a link to a new |
727 |
|
|
version. The <c>redirect</c> attribute does just that. The user might be |
728 |
|
|
automatically redirected to the new page but you should not rely on that |
729 |
|
|
behaviour. |
730 |
|
|
</p> |
731 |
|
|
|
732 |
|
|
<pre caption="Disclaimer sample"> |
733 |
|
|
<?xml version="1.0" encoding="UTF-8"?> |
734 |
|
|
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
735 |
|
|
<!-- $Header$ --> |
736 |
|
|
|
737 |
neysx |
1.67 |
<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> |
738 |
neysx |
1.51 |
<title>Gentoo x86 Installation Guide</title> |
739 |
|
|
|
740 |
|
|
<author title="Author"> |
741 |
|
|
... |
742 |
|
|
</pre> |
743 |
|
|
|
744 |
|
|
</body> |
745 |
|
|
</section> |
746 |
neysx |
1.67 |
<section> |
747 |
|
|
<title>FAQs</title> |
748 |
|
|
<body> |
749 |
|
|
|
750 |
|
|
<p> |
751 |
|
|
FAQ documents need to start with a list of questions with links to their |
752 |
|
|
answers. Creating such a list is both time-consuming and error-prone. The list |
753 |
|
|
can be created automatically if you use a <c>faqindex</c> element as the first |
754 |
|
|
chapter of your document. This element has the same structure as a |
755 |
|
|
<c>chapter</c> to allow some introductory text. The structure of the document |
756 |
|
|
is expected to be split into chapters (at least one chapter) containing |
757 |
|
|
sections, each section containing one question specified in its <c>title</c> |
758 |
|
|
element with the answer in its <c>body</c>. The FAQ index will appear as one |
759 |
|
|
section per chapter and one link per question. |
760 |
|
|
</p> |
761 |
|
|
|
762 |
|
|
<p> |
763 |
|
|
A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri |
764 |
|
|
link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above |
765 |
|
|
obvious. |
766 |
|
|
</p> |
767 |
|
|
|
768 |
|
|
</body> |
769 |
|
|
</section> |
770 |
|
|
</chapter> |
771 |
|
|
|
772 |
|
|
<chapter> |
773 |
|
|
<title>Handbook Format</title> |
774 |
|
|
<section> |
775 |
|
|
<title>Guide vs Book</title> |
776 |
|
|
<body> |
777 |
|
|
|
778 |
|
|
<p> |
779 |
|
|
For high-volume documentation, such as the <uri |
780 |
|
|
link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
781 |
|
|
broader format was needed. We designed a GuideXML-compatible enhancement that |
782 |
|
|
allows us to write modular and multi-page documentation. |
783 |
|
|
</p> |
784 |
|
|
|
785 |
|
|
</body> |
786 |
|
|
</section> |
787 |
|
|
<section> |
788 |
|
|
<title>Main File</title> |
789 |
|
|
<body> |
790 |
|
|
|
791 |
|
|
<p> |
792 |
|
|
The first change is the need for a "master" document. This document contains no |
793 |
|
|
real content, but links to the individual documentation modules. The syntax |
794 |
|
|
doesn't differ much from GuideXML: |
795 |
|
|
</p> |
796 |
|
|
|
797 |
|
|
<pre caption="Example book usage"> |
798 |
|
|
<?xml version='1.0' encoding='UTF-8'?> |
799 |
|
|
<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
800 |
|
|
<!-- $Header$ --> |
801 |
|
|
|
802 |
|
|
<<i>book</i>> |
803 |
|
|
<title>Example Book Usage</title> |
804 |
|
|
|
805 |
|
|
<author...> |
806 |
|
|
... |
807 |
|
|
</author> |
808 |
|
|
|
809 |
|
|
<abstract> |
810 |
|
|
... |
811 |
|
|
</abstract> |
812 |
|
|
|
813 |
|
|
<!-- The content of this document is licensed under the CC-BY-SA license --> |
814 |
swift |
1.71 |
<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
815 |
|
|
<license version="3.0"/> |
816 |
neysx |
1.67 |
|
817 |
|
|
<version>...</version> |
818 |
|
|
<date>...</date> |
819 |
|
|
</pre> |
820 |
|
|
|
821 |
|
|
<p> |
822 |
|
|
So far no real differences (except for the <c><book></c> instead of |
823 |
|
|
<c><guide></c> tag). Instead of starting with the individual |
824 |
|
|
<c><chapter></c>s, you define a <c><part></c>, which is the |
825 |
|
|
equivalent of a separate part in a book: |
826 |
|
|
</p> |
827 |
|
|
|
828 |
|
|
<pre caption="Defining a part"> |
829 |
|
|
<part> |
830 |
|
|
<title>Part One</title> |
831 |
|
|
<abstract> |
832 |
|
|
... |
833 |
|
|
</abstract> |
834 |
|
|
|
835 |
|
|
<comment>(Defining the several chapters)</comment> |
836 |
|
|
</part> |
837 |
|
|
</pre> |
838 |
|
|
|
839 |
|
|
<p> |
840 |
|
|
Each part is accompanied by a <c><title></c> and an |
841 |
|
|
<c><abstract></c> which gives a small introduction to the part. |
842 |
|
|
</p> |
843 |
|
|
|
844 |
|
|
<p> |
845 |
|
|
Inside each part, you define the individual <c><chapter></c>s. Each |
846 |
|
|
chapter <e>must</e> be a separate document. As a result it is no surprise that |
847 |
|
|
a special tag (<c><include></c>) is added to allow including the separate |
848 |
|
|
document. |
849 |
|
|
</p> |
850 |
|
|
|
851 |
|
|
<pre caption="Defining a chapter"> |
852 |
|
|
<chapter> |
853 |
|
|
<title>Chapter One</title> |
854 |
|
|
|
855 |
|
|
<include href="path/to/chapter-one.xml"/> |
856 |
|
|
|
857 |
|
|
</chapter> |
858 |
|
|
</pre> |
859 |
|
|
|
860 |
|
|
</body> |
861 |
|
|
</section> |
862 |
|
|
<section> |
863 |
|
|
<title>Designing the Individual Chapters</title> |
864 |
|
|
<body> |
865 |
|
|
|
866 |
|
|
<p> |
867 |
|
|
The content of an individual chapter is structured as follows: |
868 |
|
|
</p> |
869 |
|
|
|
870 |
|
|
<pre caption="Chapter Syntax"> |
871 |
|
|
<?xml version='1.0' encoding='UTF-8'?> |
872 |
|
|
<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
873 |
|
|
<!-- $Header$ --> |
874 |
|
|
|
875 |
|
|
<!-- The content of this document is licensed under the CC-BY-SA license --> |
876 |
swift |
1.71 |
<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
877 |
neysx |
1.67 |
|
878 |
|
|
<sections> |
879 |
|
|
|
880 |
|
|
<abstract> |
881 |
|
|
This is a small explanation on chapter one. |
882 |
|
|
</abstract> |
883 |
|
|
|
884 |
|
|
<version>...</version> |
885 |
|
|
<date>...</date> |
886 |
|
|
|
887 |
|
|
<comment>(Define the several <section> and <subsection>)</comment> |
888 |
|
|
|
889 |
|
|
</sections> |
890 |
|
|
</pre> |
891 |
|
|
|
892 |
|
|
<p> |
893 |
|
|
Inside each chapter you can define <c><section></c>s (equivalent of |
894 |
|
|
<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent |
895 |
|
|
of <c><section></c> in a Guide). |
896 |
|
|
</p> |
897 |
|
|
|
898 |
|
|
<p> |
899 |
|
|
Each individual chapter should have its own date and version elements. The |
900 |
|
|
latest date of all chapters and master document will be displayed when a user |
901 |
|
|
browses through all parts of the book. |
902 |
|
|
</p> |
903 |
|
|
|
904 |
|
|
</body> |
905 |
|
|
</section> |
906 |
swift |
1.17 |
</chapter> |
907 |
|
|
|
908 |
|
|
<chapter> |
909 |
neysx |
1.67 |
<title>Advanced Handbook Features</title> |
910 |
|
|
<section> |
911 |
|
|
<title>Global Values</title> |
912 |
|
|
<body> |
913 |
|
|
|
914 |
|
|
<p> |
915 |
|
|
Sometimes, the same values are repeated many times in several parts of a |
916 |
|
|
handbook. Global search and replace operations tend to forget some or introduce |
917 |
|
|
unwanted changes. Besides, it can be useful to define different values to be |
918 |
|
|
used in shared chapters depending on which handbook includes the chapter. |
919 |
|
|
</p> |
920 |
|
|
|
921 |
|
|
<p> |
922 |
|
|
Global values can be defined in a handbook master file and used in all included |
923 |
|
|
chapters. |
924 |
|
|
</p> |
925 |
|
|
|
926 |
|
|
<p> |
927 |
|
|
To define global values, add a <c><values></c> element to the handbook |
928 |
|
|
master file. Each value is then defined in a <c><key></c> element whose |
929 |
|
|
<c>id</c> attribute identifies the value, i.e. it is the name of your variable. |
930 |
|
|
The content of the <c><key></c> is its value. |
931 |
|
|
</p> |
932 |
|
|
|
933 |
|
|
<p> |
934 |
|
|
The following example defines three values in a handbook master file: |
935 |
|
|
</p> |
936 |
|
|
|
937 |
|
|
<pre caption="Define values in a handbook"> |
938 |
|
|
<?xml version='1.0' encoding='UTF-8'?> |
939 |
|
|
<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
940 |
|
|
<!-- $Header$ --> |
941 |
|
|
|
942 |
|
|
<book> |
943 |
|
|
<title>Example Book Usage</title> |
944 |
|
|
|
945 |
|
|
<i><values> |
946 |
|
|
<key id="arch">x86</key> |
947 |
|
|
<key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> |
948 |
|
|
<key id="min-cd-size">57</key> |
949 |
|
|
</values></i> |
950 |
|
|
|
951 |
|
|
<author...> |
952 |
|
|
... |
953 |
|
|
</author> |
954 |
|
|
|
955 |
|
|
... |
956 |
|
|
</pre> |
957 |
|
|
|
958 |
|
|
<p> |
959 |
|
|
The defined values can then be used throughout the handbook with the in-line |
960 |
|
|
<c><keyval id="key_id"/></c> element. Specify the name of the key in its |
961 |
|
|
<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by |
962 |
|
|
"install-x86-minimal-2007.0-r1.iso" in our example. |
963 |
|
|
</p> |
964 |
|
|
|
965 |
|
|
<pre caption="Using defined values"> |
966 |
|
|
<p> |
967 |
|
|
The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> |
968 |
|
|
and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this |
969 |
|
|
Installation CD to install Gentoo, but <e>only</e> with a working Internet |
970 |
|
|
connection. |
971 |
|
|
</p> |
972 |
|
|
</pre> |
973 |
|
|
|
974 |
|
|
<p> |
975 |
|
|
To make life easier on our translators, only use actual values, i.e. content |
976 |
|
|
that does not need to be translated. For instance, we defined the |
977 |
|
|
<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. |
978 |
|
|
</p> |
979 |
|
|
|
980 |
|
|
</body> |
981 |
|
|
</section> |
982 |
|
|
<section> |
983 |
|
|
<title>Conditional Elements</title> |
984 |
|
|
<body> |
985 |
|
|
|
986 |
|
|
<p> |
987 |
|
|
Chapters that are shared by several handbooks such as our <uri |
988 |
|
|
link="/doc/en/handbook/">Installation Handbooks</uri> often have small |
989 |
|
|
differences depending on which handbook includes them. Instead of adding |
990 |
|
|
content that is irrelevant to some handbooks, authors can add a condition to |
991 |
|
|
the following elements: <c><section></c>, <c><subsection></c>, |
992 |
|
|
<c><body></c>, <c><note></c>, <c><impo></c>, |
993 |
|
|
<c><warn></c>, <c><pre></c>, <c><p></c>, |
994 |
|
|
<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> |
995 |
|
|
and <c><li></c>. |
996 |
|
|
</p> |
997 |
|
|
|
998 |
|
|
<p> |
999 |
|
|
The condition must be an <uri |
1000 |
|
|
link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be |
1001 |
|
|
evaluated when transforming the XML. If it evaluates to <c>true</c>, the |
1002 |
|
|
element is processed, if not, it is ignored. The condition is specified in a |
1003 |
|
|
<c>test</c> attribute. |
1004 |
|
|
</p> |
1005 |
|
|
|
1006 |
|
|
<p> |
1007 |
|
|
The following example uses the <c>arch</c> value that is defined in each |
1008 |
|
|
handbook master file to condition some content: |
1009 |
|
|
</p> |
1010 |
|
|
|
1011 |
|
|
<pre caption="Using conditional elements"> |
1012 |
|
|
<body test="contains('AMD64 x86',func:keyval('arch'))"> |
1013 |
|
|
|
1014 |
|
|
<p> |
1015 |
|
|
This paragraph applies to both x86 and AMD64 architectures. |
1016 |
|
|
</p> |
1017 |
|
|
|
1018 |
|
|
<p test="func:keyval('arch')='x86'"> |
1019 |
|
|
This paragraph only applies to the x86 architecture. |
1020 |
|
|
</p> |
1021 |
|
|
|
1022 |
|
|
<p test="func:keyval('arch')='AMD64'"> |
1023 |
|
|
This paragraph only applies to the AMD64 architecture. |
1024 |
|
|
</p> |
1025 |
|
|
|
1026 |
|
|
<p test="func:keyval('arch')='PPC'"> |
1027 |
|
|
This paragraph will never be seen! |
1028 |
|
|
The whole body is skipped because of the first condition. |
1029 |
|
|
</p> |
1030 |
|
|
|
1031 |
|
|
</body> |
1032 |
|
|
|
1033 |
|
|
<body test="contains('AMD64 PPC64',func:keyval('arch'))"> |
1034 |
|
|
|
1035 |
|
|
<p> |
1036 |
|
|
This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because |
1037 |
|
|
the 'AMD64 PPC64' string does contain 'PPC'. |
1038 |
|
|
</p> |
1039 |
|
|
|
1040 |
|
|
<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> |
1041 |
|
|
This note only applies to the AMD64 and PPC64 architectures. |
1042 |
|
|
</note> |
1043 |
|
|
|
1044 |
|
|
</body> |
1045 |
|
|
</pre> |
1046 |
|
|
|
1047 |
|
|
</body> |
1048 |
|
|
</section> |
1049 |
|
|
</chapter> |
1050 |
|
|
|
1051 |
|
|
<chapter id="codingstyle"> |
1052 |
swift |
1.17 |
<title>Coding Style</title> |
1053 |
|
|
<section> |
1054 |
|
|
<title>Introduction</title> |
1055 |
|
|
<body> |
1056 |
|
|
|
1057 |
|
|
<p> |
1058 |
|
|
Since all Gentoo Documentation is a joint effort and several people will |
1059 |
|
|
most likely change existing documentation, a coding style is needed. |
1060 |
|
|
A coding style contains two sections. The first one is regarding |
1061 |
swift |
1.45 |
internal coding - how the XML-tags are placed. The second one is |
1062 |
swift |
1.17 |
regarding the content - how not to confuse the reader. |
1063 |
|
|
</p> |
1064 |
|
|
|
1065 |
|
|
<p> |
1066 |
|
|
Both sections are described next. |
1067 |
|
|
</p> |
1068 |
|
|
|
1069 |
|
|
</body> |
1070 |
|
|
</section> |
1071 |
|
|
<section> |
1072 |
|
|
<title>Internal Coding Style</title> |
1073 |
|
|
<body> |
1074 |
|
|
|
1075 |
|
|
<p> |
1076 |
|
|
<b>Newlines</b> must be placed immediately after <e>every</e> |
1077 |
|
|
GuideXML-tag (both opening as closing), except for: |
1078 |
|
|
<c><version></c>, <c><date></c>, <c><title></c>, |
1079 |
|
|
<c><th></c>, <c><ti></c>, |
1080 |
|
|
<c><li></c>, <c><i></c>, <c><e></c>, |
1081 |
swift |
1.44 |
<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>, |
1082 |
neysx |
1.37 |
<c><comment></c>, <c><mail></c>. |
1083 |
swift |
1.17 |
</p> |
1084 |
|
|
|
1085 |
|
|
<p> |
1086 |
|
|
<b>Blank lines</b> must be placed immediately after <e>every</e> |
1087 |
|
|
<c><body></c> (opening tag only) and before <e>every</e> |
1088 |
|
|
<c><chapter></c>, <c><p></c>, <c><table></c>, |
1089 |
swift |
1.18 |
<c><author></c> (set), <c><pre></c>, <c><ul></c>, |
1090 |
|
|
<c><ol></c>, <c><warn></c>, <c><note></c> and |
1091 |
|
|
<c><impo></c> (opening tags only). |
1092 |
swift |
1.17 |
</p> |
1093 |
|
|
|
1094 |
|
|
<p> |
1095 |
|
|
<b>Word-wrapping</b> must be applied at 80 characters except inside |
1096 |
neysx |
1.51 |
<c><pre></c>. You may only deviate from this rule when there is no other |
1097 |
|
|
choice (for instance when a URL exceeds the maximum amount of characters). The |
1098 |
|
|
editor must then wrap whenever the first whitespace occurs. You should try to |
1099 |
|
|
keep the <e>rendered</e> content of <c><pre></c> elements within 80 |
1100 |
|
|
columns to help console users. |
1101 |
swift |
1.17 |
</p> |
1102 |
|
|
|
1103 |
|
|
<p> |
1104 |
neysx |
1.51 |
<b>Indentation</b> may not be used, except with the XML-constructs of which the |
1105 |
|
|
parent XML-tags are <c><tr></c> (from <c><table></c>), |
1106 |
neysx |
1.53 |
<c><ul></c>, <c><ol></c>, <c><dl></c>, and |
1107 |
|
|
<c><author></c>. If indentation is used, it <e>must</e> be two spaces for |
1108 |
|
|
each indentation. That means <e>no tabs</e> and <e>not</e> more spaces. |
1109 |
|
|
Besides, tabs are not allowed in GuideXML documents. |
1110 |
swift |
1.17 |
</p> |
1111 |
|
|
|
1112 |
|
|
<p> |
1113 |
neysx |
1.53 |
In case word-wrapping happens in <c><ti></c>, <c><th></c>, |
1114 |
neysx |
1.57 |
<c><li></c> or <c><dd></c> constructs, indentation must be used for |
1115 |
neysx |
1.53 |
the content. |
1116 |
swift |
1.17 |
</p> |
1117 |
|
|
|
1118 |
|
|
<p> |
1119 |
|
|
An example for indentation is: |
1120 |
|
|
</p> |
1121 |
|
|
|
1122 |
neysx |
1.37 |
<pre caption="Indentation Example"> |
1123 |
swift |
1.17 |
<table> |
1124 |
|
|
<tr> |
1125 |
|
|
<th>Foo</th> |
1126 |
|
|
<th>Bar</th> |
1127 |
|
|
</tr> |
1128 |
|
|
<tr> |
1129 |
swift |
1.48 |
<ti>This is an example for indentation</ti> |
1130 |
swift |
1.17 |
<ti> |
1131 |
|
|
In case text cannot be shown within an 80-character wide line, you |
1132 |
swift |
1.48 |
must use indentation if the parent tag allows it |
1133 |
swift |
1.17 |
</ti> |
1134 |
|
|
</tr> |
1135 |
|
|
</table> |
1136 |
|
|
|
1137 |
|
|
<ul> |
1138 |
|
|
<li>First option</li> |
1139 |
|
|
<li>Second option</li> |
1140 |
|
|
</ul> |
1141 |
|
|
</pre> |
1142 |
|
|
|
1143 |
|
|
<p> |
1144 |
neysx |
1.53 |
<b>Attributes</b> may not have spaces in between the attribute, the "=" mark, |
1145 |
|
|
and the attribute value. As an example: |
1146 |
swift |
1.17 |
</p> |
1147 |
|
|
|
1148 |
|
|
<pre caption="Attributes"> |
1149 |
|
|
<comment>Wrong :</comment> <pre caption = "Attributes"> |
1150 |
|
|
<comment>Correct:</comment> <pre caption="Attributes"> |
1151 |
|
|
</pre> |
1152 |
|
|
|
1153 |
|
|
</body> |
1154 |
|
|
</section> |
1155 |
|
|
<section> |
1156 |
|
|
<title>External Coding Style</title> |
1157 |
|
|
<body> |
1158 |
|
|
|
1159 |
|
|
<p> |
1160 |
neysx |
1.53 |
Inside tables (<c><table></c>) and listings (<c><ul></c>, |
1161 |
|
|
<c><ol></c>) and <c><dl></c>, periods (".") should not be used |
1162 |
|
|
unless multiple sentences are used. In that case, every sentence should end |
1163 |
|
|
with a period (or other reading marks). |
1164 |
swift |
1.17 |
</p> |
1165 |
|
|
|
1166 |
|
|
<p> |
1167 |
|
|
Every sentence, including those inside tables and listings, should start |
1168 |
|
|
with a capital letter. |
1169 |
|
|
</p> |
1170 |
|
|
|
1171 |
|
|
<pre caption="Periods and capital letters"> |
1172 |
|
|
<ul> |
1173 |
|
|
<li>No period</li> |
1174 |
|
|
<li>With period. Multiple sentences, remember?</li> |
1175 |
|
|
</ul> |
1176 |
|
|
</pre> |
1177 |
|
|
|
1178 |
|
|
<p> |
1179 |
|
|
Code Listings should <e>always</e> have a <c>caption</c>. |
1180 |
|
|
</p> |
1181 |
|
|
|
1182 |
|
|
<p> |
1183 |
|
|
Try to use <c><uri></c> with the <c>link</c> attribute as much as |
1184 |
neysx |
1.35 |
possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo |
1185 |
|
|
Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>. |
1186 |
swift |
1.15 |
</p> |
1187 |
swift |
1.18 |
|
1188 |
|
|
<p> |
1189 |
neysx |
1.37 |
When you comment something inside a <c><pre></c> construct, use |
1190 |
|
|
<c><comment></c> and parentheses or the comment marker for the language |
1191 |
|
|
that is being used (<c>#</c> for bash scripts and many other things, <c>//</c> |
1192 |
|
|
for C code, etc.) Also place the comment <e>before</e> the subject of the |
1193 |
|
|
comment. |
1194 |
swift |
1.18 |
</p> |
1195 |
|
|
|
1196 |
|
|
<pre caption="Comment example"> |
1197 |
|
|
<comment>(Substitute "john" with your user name)</comment> |
1198 |
|
|
# <i>id john</i> |
1199 |
|
|
</pre> |
1200 |
drobbins |
1.1 |
|
1201 |
|
|
</body> |
1202 |
|
|
</section> |
1203 |
|
|
</chapter> |
1204 |
swift |
1.15 |
|
1205 |
drobbins |
1.1 |
<chapter> |
1206 |
|
|
<title>Resources</title> |
1207 |
|
|
<section> |
1208 |
swift |
1.15 |
<title>Start writing</title> |
1209 |
|
|
<body> |
1210 |
|
|
|
1211 |
|
|
<p> |
1212 |
neysx |
1.67 |
GuideXML has been specially designed to be "lean and mean" so that developers |
1213 |
|
|
can spend more time writing documentation and less time learning the actual XML |
1214 |
swift |
1.15 |
syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
1215 |
neysx |
1.67 |
to start writing quality Gentoo documentation. You might be interested in our |
1216 |
|
|
<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips |
1217 |
|
|
& Tricks</uri>. If you'd like to help (or have any questions about |
1218 |
|
|
GuideXML), please post a message to the <uri |
1219 |
|
|
link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like |
1220 |
|
|
to tackle. Have fun! |
1221 |
swift |
1.15 |
</p> |
1222 |
|
|
|
1223 |
|
|
</body> |
1224 |
drobbins |
1.1 |
</section> |
1225 |
|
|
</chapter> |
1226 |
|
|
</guide> |