/[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.12 - (hide annotations) (download) (as text)
Mon May 12 21:37:58 2003 UTC (11 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.11: +10 -2 lines
File MIME type: application/xml
Fix http://bugs.gentoo.org/show_bug.cgi?id=20789

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

  ViewVC Help
Powered by ViewVC 1.1.20