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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.14 - (show annotations) (download) (as text)
Mon Aug 4 07:53:11 2003 UTC (15 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.13: +9 -1 lines
File MIME type: application/xml
Added information about the license-tag

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>
6 <author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
7 <author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
8 <author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>
10 <license/>
12 <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>
17 <version>2.0</version>
18 <date>4th of August 2003</date>
20 <chapter>
21 <title>Guide basics</title>
23 <section>
24 <title>Guide XML design goals</title>
25 <body>
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>
33 <p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
34 documents.</p>
36 </body>
37 </section>
39 <section>
40 <title>How to transform guide XML into HTML</title>
41 <body>
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 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 exactly how to transform the contents of the source guide XML document to
48 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>
52 <pre caption="Installing libxslt">
53 # <c>emerge libxslt</c>
54 </pre>
56 <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>
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>
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 </p>
72 <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>
83 <pre caption="Transforming gentoo-x86-install.xml">
84 # <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
85 </pre>
87 <p> If all went well, you should have a web-ready version of
88 <path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document
89 to display properly in a web browser, you may have to copy some files from
90 <path>htdocs</path> to <path>/tmp</path>, such
91 as <path>css/main.css</path> and (to be safe) the entire <path>images</path>
92 directory.
93 </p>
95 </body>
96 </section>
97 </chapter>
98 <chapter>
99 <title>Guide XML</title>
100 <section>
101 <title>Basic structure</title>
102 <body>
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>
108 <pre caption="The initial part of a guide XML document">
109 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
110 &lt;guide link="relative_link_to_your_guide"&gt;
111 &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;
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;
124 &lt;license/&gt;
126 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
127 &lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
128 </pre>
130 <p>On the first, line, we see the requisite tag that identifies this as an XML
131 document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
132 guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
133 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
134 guide document. </p>
136 <p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
137 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
138 allows for an optional <c>title=</c> element, used to specify the author's
139 relationship to the document (author, co-author, editor, etc.). In this
140 particular example, the authors' names are enclosed in another tag -- a
141 <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
142 person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
143 more than one <c>&lt;author&gt;</c> element is required per guide document.
144 </p>
146 <p>Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
147 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
148 current version number, and the current version date (in DD MMM YYYY format)
149 respectively. This rounds out the tags that should appear at the beginning of
150 a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
151 tags, these tags shouldn't appear anywhere else except immediately inside the
152 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
153 required) that these tags appear before the content of the document. </p>
155 <p>Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
156 document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
157 Commons - Attribution / Share Alike</uri> license as required by the <uri
158 link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
159 </p>
161 </body>
162 </section>
164 <section>
165 <title>Chapters and sections</title>
166 <body>
167 <p>Once the initial tags have been specified, you're ready to start adding
168 the structural elements of the document. Guide documents are divided into
169 chapters, and each chapter can hold one or more sections. Every chapter
170 and section has a title. Here's an example chapter with a single section,
171 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous
172 excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
173 (if minimal) guide document:
174 </p>
176 <pre>
177 &lt;chapter&gt;
178 &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
179 &lt;section&gt;
180 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
181 &lt;body&gt;
182 &lt;p&gt;<i>This is the actual text content of my section.</i>&lt;/p&gt;
183 &lt;/body&gt;
184 &lt;/section&gt;
185 &lt;/chapter&gt;
186 </pre>
188 <p>Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
189 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
190 adding a <c>&lt;section&gt;</c> element. If you look inside the
191 <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
192 <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
193 is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
194 content of this particular section. We'll look at the tags that are allowed
195 inside a <c>&lt;body&gt;</c> element in a bit. </p>
197 <note>A <c>&lt;guide&gt;</c> element can contain multiple
198 <c>&lt;chapter&gt;</c> elements, and a <c>&lt;chapter&gt;</c> can contain
199 multiple <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
200 element can only contain one <c>&lt;body&gt;</c> element. </note>
202 </body>
203 </section>
205 <section>
206 <title>An example &lt;body&gt;</title>
207 <body>
208 <p>
209 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:
210 </p>
211 <pre>
212 &lt;p&gt;
213 This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
214 &lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
215 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.
216 &lt;/p&gt;
218 &lt;pre&gt;
219 This is text output or code.
220 # &lt;i&gt;this is user input&lt;/i&gt;
222 Make HTML/XML easier to read by using selective emphasis:
223 &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
225 &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
226 &lt;/pre&gt;
227 &lt;note&gt;This is a note.&lt;/note&gt;
228 &lt;warn&gt;This is a warning.&lt;/warn&gt;
229 &lt;impo&gt;This is important.&lt;/impo&gt;
230 </pre>
231 <p>Now, here's how this <c>&lt;body&gt;</c> element is rendered:</p>
233 <p>
234 This is a paragraph. <path>/etc/passwd</path> is a file.
235 <uri>http://www.gentoo.org</uri> is my favorite website.
236 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
237 </p>
239 <pre>
240 This is text output or code.
241 # <i>this is user input</i>
243 Make HTML/XML easier to read by using selective emphasis:
244 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
246 <codenote>This is how to insert an inline note into the code block</codenote>
247 </pre>
248 <note>This is a note.</note>
249 <warn>This is a warning.</warn>
250 <impo>This is important.</impo>
251 </body>
252 </section>
254 <section>
255 <title>The &lt;body&gt; tags</title>
256 <body>
258 <p> We introduced a lot of new tags in the previous section -- here's what you
259 need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
260 block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
261 <c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
262 Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
263 these are the only tags that should appear immediately inside a
264 <c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
265 stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
266 <c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
267 preserves its whitespace exactly, making it well-suited for code excerpts.
268 You can also name the <c>&lt;pre&gt;</c> tag:</p>
270 <pre caption = "Named &lt;pre&gt;">
271 &lt;pre caption = "Output of uptime"&gt;
272 # &lt;i&gt;uptime&lt;/i&gt;
273 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
274 &lt;/pre&gt;
275 </pre>
277 </body>
278 </section>
279 <section>
280 <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
281 <body>
283 <p>The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
284 be used inside any child <c>&lt;body&gt;</c> tag, except for
285 <c>&lt;pre&gt;</c>. </p>
287 <p>The <c>&lt;path&gt;</c> element is used to mark text that refers to an
288 <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>.
289 This element is generally rendered with a monospaced font to offset it from the
290 standard paragraph type. </p>
292 <p>The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
293 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
294 that they can type in that will perform some kind of action. For example, all
295 the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
296 element because they represent something that the user could type in that is
297 not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
298 quickly identify commands that they need to type in. Also, because
299 <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
300 necessary to surround user input with double-quotes</e>. For example, don't
301 refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
302 the use of unnecessary double-quotes makes a document more readable -- and adorable!</p>
304 <p><c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
305 I <e>really</e> should use semicolons more often. As you can see, this text is
306 offset from the regular paragraph type for emphasis. This helps to give your
307 prose more <e>punch</e>!</p>
309 </body>
310 </section>
312 <section>
313 <title>&lt;mail&gt; and &lt;uri&gt;</title>
314 <body>
316 <p>We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link some text
317 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>
319 <p>The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
320 Internet. It has two forms -- the first can be used when you want to have the
321 actual URI displayed in the body text, such as this link to
322 <uri>http://www.gentoo.org</uri>. To create this link, I typed
323 <c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
324 when you want to associate a URI with some other text -- for example, <uri
325 link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e>
326 link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the Gentoo Linux website&lt;/uri&gt;</c>.
327 </p>
329 </body>
330 </section>
332 <section>
333 <title>Figures</title>
335 <body>
337 <p>Here's how to insert a figure into a document -- <c>&lt;figure
338 link="mygfx.png" short="my picture" caption="my favorite picture of all
339 time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
340 the <c>short=</c> attribute specifies a short description (currently used for
341 the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
342 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
343 for adding images without captions, borders, etc.</p>
345 </body>
346 </section>
347 <section>
348 <title>Tables and lists</title>
349 <body>
351 <p>Guide supports a simplified table syntax similar to that of HTML. To start
352 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
353 tag. However, for inserting actual table data, we <e>don't</e> support the
354 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
355 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
356 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> --
357 there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
358 first row. Currently, these tags don't support any attributes, but some will
359 be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
360 </p>
362 <p> To create ordered or unordered lists, simply use the HTML-style
363 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
364 should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
365 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag. </p>
367 </body>
368 </section>
370 <section>
371 <title>Intra-document references</title>
372 <body>
374 <p>Guide makes it really easy to reference other parts of the document using
375 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
376 One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
377 One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
378 Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
379 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
380 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>,
381 type <c>&lt;uri link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
382 adding other auto-link abilities (such as table support) soon.</p>
384 </body>
385 </section>
386 </chapter>
387 <chapter>
388 <title>Resources</title>
389 <section>
390 <title>Start writing</title>
391 <body>
392 <p>Guide has been specially designed to be "lean and mean" so that developers
393 can spend more time writing documentation and less time learning the actual XML
394 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
395 to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please
396 post a message to the <mail link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail>
397 stating what you'd like to tackle.
398 Have fun!</p>
399 </body>
400 </section>
401 </chapter>
402 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20