/[gentoo]/xml/htdocs/doc/en/xml-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/xml-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.16 - (show annotations) (download) (as text)
Fri Oct 10 15:29:09 2003 UTC (10 years, 6 months ago) by neysx
Branch: MAIN
Changes since 1.15: +1 -1 lines
File MIME type: application/xml
Changed dead internal link

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <guide link="/doc/en/xml-guide.xml">
5 <title>Gentoo Linux XML Guide</title>
6
7 <author title="Author">
8 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
9 </author>
10 <author title="Author">
11 <mail link="zhen@gentoo.org">John P. Davis</mail>
12 </author>
13 <author title="Editor">
14 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
15 </author>
16
17 <license/>
18 <abstract>
19 This guide shows you how to compose web documentation using the new lightweight
20 Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21 documentation, and this document itself was created using GuideXML. This guide
22 assumes a basic working knowledge of XML and HTML.
23 </abstract>
24
25 <version>2.0</version>
26 <date>October 9, 2003</date>
27
28 <chapter>
29 <title>Guide basics</title>
30
31 <section>
32 <title>Guide XML design goals</title>
33 <body>
34
35 <p>
36 The guide XML syntax is lightweight yet expressive, so that it is easy to
37 learn yet also provides all the features we need for the creation of web
38 documentation. The number of tags is kept to a minimum -- just those we need.
39 This makes it easy to transform guide into other formats, such as DocBook
40 XML/SGML or web-ready HTML.
41 </p>
42
43 <p>
44 The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45 documents.
46 </p>
47
48 </body>
49 </section>
50
51 <section>
52 <title>How to transform guide XML into HTML</title>
53 <body>
54
55 <p>
56 Before we take a look at the guide syntax itself, it's helpful to know how
57 guide XML is transformed into web-ready HTML. To do this, we use a special
58 file called <path>guide.xsl</path>, along with a command-line XSLT processing
59 tool (also called an "engine"). The <path>guide.xsl</path> file describes
60 exactly how to transform the contents of the source guide XML document to
61 create the target HTML file. The processing tool that Gentoo Linux uses
62 is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
63 </p>
64
65 <pre caption="Installing libxslt">
66 # <c>emerge libxslt</c>
67 </pre>
68
69 <p>
70 Now that we have the way, we need the means, so to speak. In other words,
71 we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
72 that are available for download:
73 </p>
74
75 <p>
76 <b>The first type contains the entire up-to-date Gentoo Linux website</b>.
77 Included are our XSL templates, so if you are planning to transform any
78 documentation, you will need this tarball. The tarball can be found <uri
79 link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
80 </p>
81
82 <p>
83 <b>The second type contains daily snapshots our XML documentation source</b>
84 in every language that we offer. Please note that it is impossible to transform
85 documentation with this tarball, so please download the web tarball if you want
86 to fully develop your own documentation. These tarballs are especially useful
87 for translators. These tarballs can be found <uri
88 link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
89 </p>
90
91 <p>
92 After the web tarball is downloaded and extracted, go to the directory where
93 the tarball was extracted, and enter the <path>htdocs</path> directory. Browse
94 around and get comfortable with the layout, but note the <path>xsl</path> and
95 <path>doc</path> directories. As you might have guessed, the XSL stylesheets are
96 in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing
97 purposes, we will be using the Gentoo Linux CD Installation Guide, located at
98 <path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL
99 and XML file are known, we can do some transforming with <c>xsltproc</c>.
100 </p>
101
102 <pre caption="Transforming gentoo-x86-install.xml">
103 # <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
104 </pre>
105
106 <p>
107 If all went well, you should have a web-ready version of
108 <path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For
109 this document to display properly in a web browser, you may have to copy some
110 files from <path>htdocs</path> to <path>/tmp</path>, such as
111 <path>css/main.css</path> and (to be safe) the entire <path>images</path>
112 directory.
113 </p>
114
115 </body>
116 </section>
117 </chapter>
118
119 <chapter>
120 <title>Guide XML</title>
121 <section>
122 <title>Basic structure</title>
123 <body>
124
125 <p>
126 Now that you know how to transform guide XML, you're ready to start learning
127 the GuideXML syntax. We'll start with the the initial tags used in a guide
128 XML document:
129 </p>
130
131 <pre caption="The initial part of a guide XML document">
132 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
133 &lt;guide link="relative_link_to_your_guide"&gt;
134 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
135 &lt;author title="<i>Chief Architect</i>"&gt;
136 &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt;
137 &lt;/author&gt;
138 &lt;author title="<i>Editor</i>"&gt;
139 &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt;
140 &lt;/author&gt;
141
142 &lt;abstract&gt;
143 <i>This guide shows you how to compose web documentation using
144 our new lightweight Gentoo GuideXML syntax. This syntax is the official
145 format for Gentoo Linux web documentation, and this document itself was created
146 using GuideXML.</i>
147 &lt;/abstract&gt;
148
149 &lt;license/&gt;
150
151 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
152 &lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
153 </pre>
154
155 <p>
156 On the first, line, we see the requisite tag that identifies this as an XML
157 document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
158 guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
159 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
160 guide document.
161 </p>
162
163 <p>
164 Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
165 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
166 allows for an optional <c>title=</c> element, used to specify the author's
167 relationship to the document (author, co-author, editor, etc.). In this
168 particular example, the authors' names are enclosed in another tag -- a
169 <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
170 person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
171 more than one <c>&lt;author&gt;</c> element is required per guide document.
172 </p>
173
174 <p>
175 Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
176 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
177 current version number, and the current version date (in DD MMM YYYY format)
178 respectively. This rounds out the tags that should appear at the beginning of
179 a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
180 tags, these tags shouldn't appear anywhere else except immediately inside the
181 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
182 required) that these tags appear before the content of the document.
183 </p>
184
185 <p>
186 Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
187 document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
188 Commons - Attribution / Share Alike</uri> license as required by the <uri
189 link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
190 </p>
191
192 </body>
193 </section>
194
195 <section>
196 <title>Chapters and sections</title>
197 <body>
198
199 <p>
200 Once the initial tags have been specified, you're ready to start adding
201 the structural elements of the document. Guide documents are divided into
202 chapters, and each chapter can hold one or more sections. Every chapter
203 and section has a title. Here's an example chapter with a single section,
204 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
205 excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
206 (if minimal) guide document:
207 </p>
208
209 <pre>
210 &lt;chapter&gt;
211 &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
212 &lt;section&gt;
213 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
214 &lt;body&gt;
215
216 &lt;p&gt;
217 <i>This is the actual text content of my section.</i>
218 &lt;/p&gt;
219
220 &lt;/body&gt;
221 &lt;/section&gt;
222 &lt;/chapter&gt;
223 </pre>
224
225 <p>
226 Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
227 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
228 adding a <c>&lt;section&gt;</c> element. If you look inside the
229 <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
230 <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
231 is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
232 content of this particular section. We'll look at the tags that are allowed
233 inside a <c>&lt;body&gt;</c> element in a bit.
234 </p>
235
236 <note>
237 A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
238 elements, and a <c>&lt;chapter&gt;</c> can contain multiple
239 <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
240 element can only contain one <c>&lt;body&gt;</c> element.
241 </note>
242
243 </body>
244 </section>
245
246 <section>
247 <title>An example &lt;body&gt;</title>
248 <body>
249
250 <p>
251 Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c>&lt;body&gt;</c> element:
252 </p>
253
254 <pre>
255 &lt;p&gt;
256 This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
257 &lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
258 Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now.
259 &lt;/p&gt;
260
261 &lt;pre&gt;
262 This is text output or code.
263 # &lt;i&gt;this is user input&lt;/i&gt;
264
265 Make HTML/XML easier to read by using selective emphasis:
266 &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
267
268 &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
269 &lt;/pre&gt;
270
271 &lt;note&gt;
272 This is a note.
273 &lt;/note&gt;
274
275 &lt;warn&gt;
276 This is a warning.
277 &lt;/warn&gt;
278
279 &lt;impo&gt;
280 This is important.
281 &lt;/impo&gt;
282 </pre>
283
284 <p>
285 Now, here's how this <c>&lt;body&gt;</c> element is rendered:
286 </p>
287
288 <p>
289 This is a paragraph. <path>/etc/passwd</path> is a file.
290 <uri>http://www.gentoo.org</uri> is my favorite website.
291 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
292 </p>
293
294 <pre>
295 This is text output or code.
296 # <i>this is user input</i>
297
298 Make HTML/XML easier to read by using selective emphasis:
299 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
300
301 <codenote>This is how to insert an inline note into the code block</codenote>
302 </pre>
303
304 <note>
305 This is a note.
306 </note>
307
308 <warn>
309 This is a warning.
310 </warn>
311
312 <impo>
313 This is important.
314 </impo>
315
316 </body>
317 </section>
318
319 <section>
320 <title>The &lt;body&gt; tags</title>
321 <body>
322
323 <p>
324 We introduced a lot of new tags in the previous section -- here's what you
325 need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
326 block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
327 <c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
328 Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
329 these are the only tags that should appear immediately inside a
330 <c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
331 stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
332 <c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
333 preserves its whitespace exactly, making it well-suited for code excerpts.
334 You can also name the <c>&lt;pre&gt;</c> tag:
335 </p>
336
337 <pre caption = "Named &lt;pre&gt;">
338 &lt;pre caption = "Output of uptime"&gt;
339 # &lt;i&gt;uptime&lt;/i&gt;
340 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
341 &lt;/pre&gt;
342 </pre>
343
344 </body>
345 </section>
346 <section>
347 <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
348 <body>
349
350 <p>
351 The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
352 be used inside any child <c>&lt;body&gt;</c> tag, except for
353 <c>&lt;pre&gt;</c>.
354 </p>
355
356 <p>
357 The <c>&lt;path&gt;</c> element is used to mark text that refers to an
358 <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
359 <e>simple filename</e>. This element is generally rendered with a monospaced
360 font to offset it from the standard paragraph type.
361 </p>
362
363 <p>
364 The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
365 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
366 that they can type in that will perform some kind of action. For example, all
367 the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
368 element because they represent something that the user could type in that is
369 not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
370 quickly identify commands that they need to type in. Also, because
371 <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
372 necessary to surround user input with double-quotes</e>. For example, don't
373 refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
374 the use of unnecessary double-quotes makes a document more readable -- and
375 adorable!
376 </p>
377
378 <p>
379 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
380 I <e>really</e> should use semicolons more often. As you can see, this text is
381 offset from the regular paragraph type for emphasis. This helps to give your
382 prose more <e>punch</e>!
383 </p>
384
385 </body>
386 </section>
387
388 <section>
389 <title>&lt;mail&gt; and &lt;uri&gt;</title>
390 <body>
391
392 <p>
393 We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
394 some text with a particular email address, and takes the form <c>&lt;mail
395 link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
396 </p>
397
398 <p>
399 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
400 Internet. It has two forms -- the first can be used when you want to have the
401 actual URI displayed in the body text, such as this link to
402 <uri>http://www.gentoo.org</uri>. To create this link, I typed
403 <c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
404 when you want to associate a URI with some other text -- for example, <uri
405 link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
406 <e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the
407 Gentoo Linux website&lt;/uri&gt;</c>.
408 </p>
409
410 </body>
411 </section>
412
413 <section>
414 <title>Figures</title>
415
416 <body>
417
418 <p>
419 Here's how to insert a figure into a document -- <c>&lt;figure
420 link="mygfx.png" short="my picture" caption="my favorite picture of all
421 time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
422 the <c>short=</c> attribute specifies a short description (currently used for
423 the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
424 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
425 for adding images without captions, borders, etc.
426 </p>
427
428 </body>
429 </section>
430 <section>
431 <title>Tables and lists</title>
432 <body>
433
434 <p>
435 Guide supports a simplified table syntax similar to that of HTML. To start
436 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
437 tag. However, for inserting actual table data, we <e>don't</e> support the
438 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
439 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
440 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
441 -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
442 first row. Currently, these tags don't support any attributes, but some will
443 be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
444 </p>
445
446 <p>
447 To create ordered or unordered lists, simply use the HTML-style
448 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
449 should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
450 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
451 </p>
452
453 </body>
454 </section>
455
456 <section>
457 <title>Intra-document references</title>
458 <body>
459
460 <p>
461 Guide makes it really easy to reference other parts of the document using
462 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
463 One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
464 One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
465 Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
466 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
467 link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
468 link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
469 link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
470 adding other auto-link abilities (such as table support) soon.
471 </p>
472
473 </body>
474 </section>
475 </chapter>
476
477 <chapter>
478 <title>Resources</title>
479 <section>
480 <title>Start writing</title>
481 <body>
482
483 <p>
484 Guide has been specially designed to be "lean and mean" so that developers
485 can spend more time writing documentation and less time learning the actual XML
486 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
487 to start writing quality Gentoo Linux documentation. If you'd like to help (or
488 have any questions about guide), please post a message to the <mail
489 link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
490 like to tackle. Have fun!
491 </p>
492
493 </body>
494 </section>
495 </chapter>
496 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20