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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.15 - (show annotations) (download) (as text)
Thu Oct 9 11:31:11 2003 UTC (14 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.14: +212 -118 lines
File MIME type: application/xml
Internal Coding Rewrite, no (absolutely none) content changes. However, do check the <pre> stuff since coding rewrites do change the content of <pre> regarding whitespace

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 <guide link="/doc/en/xml-guide.xml">
5 <title>Gentoo Linux XML Guide</title>
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>
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>
25 <version>2.0</version>
26 <date>October 9, 2003</date>
28 <chapter>
29 <title>Guide basics</title>
31 <section>
32 <title>Guide XML design goals</title>
33 <body>
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>
43 <p>
44 The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45 documents.
46 </p>
48 </body>
49 </section>
51 <section>
52 <title>How to transform guide XML into HTML</title>
53 <body>
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>
65 <pre caption="Installing libxslt">
66 # <c>emerge libxslt</c>
67 </pre>
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>
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>
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>
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>
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>
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>
115 </body>
116 </section>
117 </chapter>
119 <chapter>
120 <title>Guide XML</title>
121 <section>
122 <title>Basic structure</title>
123 <body>
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>
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;
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;
149 &lt;license/&gt;
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>
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>
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>
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>
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>
192 </body>
193 </section>
195 <section>
196 <title>Chapters and sections</title>
197 <body>
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_pre2">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>
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;
216 &lt;p&gt;
217 <i>This is the actual text content of my section.</i>
218 &lt;/p&gt;
220 &lt;/body&gt;
221 &lt;/section&gt;
222 &lt;/chapter&gt;
223 </pre>
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>
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>
243 </body>
244 </section>
246 <section>
247 <title>An example &lt;body&gt;</title>
248 <body>
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>
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;
261 &lt;pre&gt;
262 This is text output or code.
263 # &lt;i&gt;this is user input&lt;/i&gt;
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;
268 &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
269 &lt;/pre&gt;
271 &lt;note&gt;
272 This is a note.
273 &lt;/note&gt;
275 &lt;warn&gt;
276 This is a warning.
277 &lt;/warn&gt;
279 &lt;impo&gt;
280 This is important.
281 &lt;/impo&gt;
282 </pre>
284 <p>
285 Now, here's how this <c>&lt;body&gt;</c> element is rendered:
286 </p>
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>
294 <pre>
295 This is text output or code.
296 # <i>this is user input</i>
298 Make HTML/XML easier to read by using selective emphasis:
299 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
301 <codenote>This is how to insert an inline note into the code block</codenote>
302 </pre>
304 <note>
305 This is a note.
306 </note>
308 <warn>
309 This is a warning.
310 </warn>
312 <impo>
313 This is important.
314 </impo>
316 </body>
317 </section>
319 <section>
320 <title>The &lt;body&gt; tags</title>
321 <body>
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>
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>
344 </body>
345 </section>
346 <section>
347 <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
348 <body>
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>
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>
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>
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>
385 </body>
386 </section>
388 <section>
389 <title>&lt;mail&gt; and &lt;uri&gt;</title>
390 <body>
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>
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>
410 </body>
411 </section>
413 <section>
414 <title>Figures</title>
416 <body>
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>
428 </body>
429 </section>
430 <section>
431 <title>Tables and lists</title>
432 <body>
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>
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>
453 </body>
454 </section>
456 <section>
457 <title>Intra-document references</title>
458 <body>
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>
473 </body>
474 </section>
475 </chapter>
477 <chapter>
478 <title>Resources</title>
479 <section>
480 <title>Start writing</title>
481 <body>
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>
493 </body>
494 </section>
495 </chapter>
496 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20