/[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.13 - (hide annotations) (download) (as text)
Sat Aug 2 18:35:23 2003 UTC (10 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.12: +2 -0 lines
File MIME type: application/xml
Add license tag to all documents of which the authors have agreed on

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

  ViewVC Help
Powered by ViewVC 1.1.20