/[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.15 - (hide annotations) (download) (as text)
Thu Oct 9 11:31:11 2003 UTC (10 years, 9 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 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3    
4 zhen 1.2 <guide link="/doc/en/xml-guide.xml">
5 zhen 1.9 <title>Gentoo Linux XML Guide</title>
6 swift 1.15
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 drobbins 1.1
17 swift 1.13 <license/>
18 swift 1.15 <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 drobbins 1.1 </abstract>
24    
25 zhen 1.9 <version>2.0</version>
26 swift 1.15 <date>October 9, 2003</date>
27 drobbins 1.1
28     <chapter>
29     <title>Guide basics</title>
30    
31     <section>
32     <title>Guide XML design goals</title>
33     <body>
34    
35 swift 1.15 <p>
36     The guide XML syntax is lightweight yet expressive, so that it is easy to
37 drobbins 1.1 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 swift 1.15 XML/SGML or web-ready HTML.
41     </p>
42 drobbins 1.1
43 swift 1.15 <p>
44     The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45     documents.
46     </p>
47 drobbins 1.1
48     </body>
49     </section>
50    
51     <section>
52     <title>How to transform guide XML into HTML</title>
53     <body>
54    
55 swift 1.15 <p>
56     Before we take a look at the guide syntax itself, it's helpful to know how
57 drobbins 1.1 guide XML is transformed into web-ready HTML. To do this, we use a special
58 zhen 1.6 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 drobbins 1.1 exactly how to transform the contents of the source guide XML document to
61 zhen 1.9 create the target HTML file. The processing tool that Gentoo Linux uses
62 swift 1.15 is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
63     </p>
64 zhen 1.6
65 zhen 1.9 <pre caption="Installing libxslt">
66     # <c>emerge libxslt</c>
67     </pre>
68 zhen 1.6
69 swift 1.15 <p>
70     Now that we have the way, we need the means, so to speak. In other words,
71 zhen 1.9 we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
72 swift 1.15 that are available for download:
73     </p>
74 zhen 1.9
75 swift 1.15 <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 zhen 1.6
102     <pre caption="Transforming gentoo-x86-install.xml">
103 peesh 1.11 # <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
104 drobbins 1.1 </pre>
105    
106 swift 1.15 <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 drobbins 1.1 directory.
113     </p>
114    
115     </body>
116     </section>
117     </chapter>
118 swift 1.15
119 drobbins 1.1 <chapter>
120 swift 1.15 <title>Guide XML</title>
121 drobbins 1.1 <section>
122     <title>Basic structure</title>
123     <body>
124    
125 swift 1.15 <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 drobbins 1.1
131     <pre caption="The initial part of a guide XML document">
132 zhen 1.6 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
133     &lt;guide link="relative_link_to_your_guide"&gt;
134 drobbins 1.1 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
135 swift 1.15 &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 drobbins 1.1 &lt;/author&gt;
138 swift 1.15 &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 drobbins 1.1 &lt;/author&gt;
141    
142 swift 1.15 &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 drobbins 1.1 format for Gentoo Linux web documentation, and this document itself was created
146 swift 1.15 using GuideXML.</i>
147     &lt;/abstract&gt;
148 drobbins 1.1
149 swift 1.14 &lt;license/&gt;
150    
151 drobbins 1.1 &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 swift 1.15 <p>
156     On the first, line, we see the requisite tag that identifies this as an XML
157 drobbins 1.1 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 swift 1.15 guide document.
161     </p>
162 drobbins 1.1
163 swift 1.15 <p>
164     Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
165 drobbins 1.1 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 swift 1.15 <p>
175     Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
176 drobbins 1.1 <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 swift 1.15 required) that these tags appear before the content of the document.
183     </p>
184 swift 1.14
185 swift 1.15 <p>
186     Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
187 swift 1.14 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 swift 1.15 </p>
191 drobbins 1.1
192     </body>
193     </section>
194    
195     <section>
196     <title>Chapters and sections</title>
197     <body>
198 swift 1.15
199     <p>
200     Once the initial tags have been specified, you're ready to start adding
201 drobbins 1.1 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>
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 swift 1.15 &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 drobbins 1.1 &lt;/section&gt;
222     &lt;/chapter&gt;
223     </pre>
224    
225 swift 1.15 <p>
226     Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
227 drobbins 1.1 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 swift 1.15 inside a <c>&lt;body&gt;</c> element in a bit.
234     </p>
235 drobbins 1.1
236 swift 1.15 <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 drobbins 1.1
243     </body>
244     </section>
245    
246     <section>
247     <title>An example &lt;body&gt;</title>
248     <body>
249 swift 1.15
250 drobbins 1.1 <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 swift 1.15
254 drobbins 1.1 <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 swift 1.15
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 drobbins 1.1 </pre>
283 swift 1.15
284     <p>
285     Now, here's how this <c>&lt;body&gt;</c> element is rendered:
286     </p>
287 drobbins 1.1
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 swift 1.15
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 drobbins 1.1 </body>
317     </section>
318    
319     <section>
320     <title>The &lt;body&gt; tags</title>
321     <body>
322    
323 swift 1.15 <p>
324     We introduced a lot of new tags in the previous section -- here's what you
325 drobbins 1.1 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 swift 1.12 preserves its whitespace exactly, making it well-suited for code excerpts.
334 swift 1.15 You can also name the <c>&lt;pre&gt;</c> tag:
335     </p>
336 swift 1.12
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 drobbins 1.1
344     </body>
345     </section>
346     <section>
347     <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
348     <body>
349    
350 swift 1.15 <p>
351     The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
352 drobbins 1.1 be used inside any child <c>&lt;body&gt;</c> tag, except for
353 swift 1.15 <c>&lt;pre&gt;</c>.
354     </p>
355 drobbins 1.1
356 swift 1.15 <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 drobbins 1.1
363 swift 1.15 <p>
364     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
365 drobbins 1.1 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 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
375     adorable!
376     </p>
377 drobbins 1.1
378 swift 1.15 <p>
379     <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
380 drobbins 1.1 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 swift 1.15 prose more <e>punch</e>!
383     </p>
384 drobbins 1.1
385     </body>
386     </section>
387    
388     <section>
389     <title>&lt;mail&gt; and &lt;uri&gt;</title>
390     <body>
391    
392 swift 1.15 <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 drobbins 1.1
398 swift 1.15 <p>
399     The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
400 drobbins 1.1 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 swift 1.15 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 drobbins 1.1 </p>
409    
410     </body>
411     </section>
412    
413     <section>
414     <title>Figures</title>
415    
416     <body>
417    
418 swift 1.15 <p>
419     Here's how to insert a figure into a document -- <c>&lt;figure
420 drobbins 1.1 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 swift 1.15 for adding images without captions, borders, etc.
426     </p>
427 drobbins 1.1
428     </body>
429     </section>
430     <section>
431     <title>Tables and lists</title>
432     <body>
433    
434 swift 1.15 <p>
435     Guide supports a simplified table syntax similar to that of HTML. To start
436 drobbins 1.1 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 swift 1.15 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 drobbins 1.1 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 swift 1.15 <p>
447     To create ordered or unordered lists, simply use the HTML-style
448 drobbins 1.1 <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 swift 1.15 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
451     </p>
452 drobbins 1.1
453     </body>
454     </section>
455    
456     <section>
457     <title>Intra-document references</title>
458     <body>
459    
460 swift 1.15 <p>
461     Guide makes it really easy to reference other parts of the document using
462 drobbins 1.1 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 swift 1.15 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 drobbins 1.1
473     </body>
474     </section>
475     </chapter>
476 swift 1.15
477 drobbins 1.1 <chapter>
478     <title>Resources</title>
479     <section>
480 swift 1.15 <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 drobbins 1.1 </section>
495     </chapter>
496     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20