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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (show annotations) (download) (as text)
Sat Nov 9 18:47:44 2002 UTC (16 years, 4 months ago) by drobbins
Branch: MAIN
File MIME type: application/xml
try #10030

1 <?xml version='1.0'?>
2 <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6 <guide link="/doc/xml-guide.html">
7 <title>Gentoo Linux Documentation Guide</title>
8 <author title="Chief Architect"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
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>
15 <version>1.0</version>
16 <date>07 Mar 2002</date>
18 <chapter>
19 <title>Guide basics</title>
21 <section>
22 <title>Guide XML design goals</title>
23 <body>
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>
31 <p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
32 documents.</p>
34 </body>
35 </section>
37 <section>
38 <title>How to transform guide XML into HTML</title>
39 <body>
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 file called <path>guide-main.xsl</path>, along with a command-line XSLT processing
44 tool (also called an "engine"). The <path>guide-main.xsl</path> file describes
45 exactly how to transform the contents of the source guide XML document to
46 create the target HTML file. Two popular XSLT processors are <c>sabcmd</c>
47 (included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c>
48 (found in the <path>dev-libs/libxslt</path> package). From experience, we've
49 found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
50 processor. </p>
52 <p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're
53 ready to convert guide XML into web-ready HTML. Here's how it works. First,
54 download the latest snapshot of our Web site from
55 <uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri
56 link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri>
57 file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path>
58 directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find
59 <path>gentoo-src/xml/install.xml</path>. (The new user installation guide).
60 This will be our source XML guide document. The easiest way to perform the
61 transformation is to change directories to the location of the
62 <path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
63 </p>
65 <pre>
66 # <i>cd gentoo-web/xsl</i>
67 # <i>xsltproc guide-main.xsl ../xml/install.xml &gt; /tmp/install.html</i>
68 </pre>
70 <p> If all went well, you should have a web-ready version of
71 <path>install.xml</path> at <path>/tmp/install.html</path>. For this document
72 to display properly in a web browser, you may have to copy some files from
73 <path>gentoo-web</path> to <path>/tmp</path>, such
74 as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path>
75 directory.
76 </p>
78 </body>
79 </section>
80 </chapter>
81 <chapter>
82 <title>Guide XML</title>
83 <section>
84 <title>Basic structure</title>
85 <body>
87 <p>Now that you know how to transform guide XML, you're ready to start learning
88 the guide XML syntax. We'll start with the the initial tags used in a guide
89 XML document: </p>
91 <pre caption="The initial part of a guide XML document">
92 &lt;?xml version='1.0'?&gt;
93 &lt;guide&gt;
94 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
95 &lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt;
96 <i>Daniel Robbins</i>&lt;/mail&gt;
97 &lt;/author&gt;
98 &lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
99 <i>Thomas Flavel</i>&lt;/mail&gt;
100 &lt;/author&gt;
102 &lt;abstract&gt;<i>This guide shows you how to compose web documentation using
103 our new lightweight Gentoo guide XML syntax. This syntax is the official
104 format for Gentoo Linux web documentation, and this document itself was created
105 using guide XML.</i> &lt;/abstract&gt;
107 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
108 &lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
109 </pre>
111 <p>On the first, line, we see the requisite tag that identifies this as an XML
112 document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
113 guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
114 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
115 guide document. </p>
117 <p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
118 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
119 allows for an optional <c>title=</c> element, used to specify the author's
120 relationship to the document (author, co-author, editor, etc.). In this
121 particular example, the authors' names are enclosed in another tag -- a
122 <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
123 person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
124 more than one <c>&lt;author&gt;</c> element is required per guide document.
125 </p>
127 <p>Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
128 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
129 current version number, and the current version date (in DD MMM YYYY format)
130 respectively. This rounds out the tags that should appear at the beginning of
131 a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
132 tags, these tags shouldn't appear anywhere else except immediately inside the
133 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
134 required) that these tags appear before the content of the document. </p>
136 </body>
137 </section>
139 <section>
140 <title>Chapters and sections</title>
141 <body>
142 <p>Once the initial tags have been specified, you're ready to start adding
143 the structural elements of the document. Guide documents are divided into
144 chapters, and each chapter can hold one or more sections. Every chapter
145 and section has a title. Here's an example chapter with a single section,
146 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous
147 excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
148 (if minimal) guide document:
149 </p>
151 <pre>
152 &lt;chapter&gt;
153 &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
154 &lt;section&gt;
155 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
156 &lt;body&gt;
157 &lt;p&gt;<i>This is the actual text content of my section.</i>&lt;/p&gt;
158 &lt;/body&gt;
159 &lt;/section&gt;
160 &lt;/chapter&gt;
161 </pre>
163 <p>Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
164 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
165 adding a <c>&lt;section&gt;</c> element. If you look inside the
166 <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
167 <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
168 is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
169 content of this particular section. We'll look at the tags that are allowed
170 inside a <c>&lt;body&gt;</c> element in a bit. </p>
172 <note>A <c>&lt;guide&gt;</c> element can contain multiple
173 <c>&lt;chapter&gt;</c> elements, and a <c>&lt;chapter&gt;</c> can contain
174 multiple <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
175 element can only contain one <c>&lt;body&gt;</c> element. </note>
177 </body>
178 </section>
180 <section>
181 <title>An example &lt;body&gt;</title>
182 <body>
183 <p>
184 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:
185 </p>
186 <pre>
187 &lt;p&gt;
188 This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
189 &lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
190 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.
191 &lt;/p&gt;
193 &lt;pre&gt;
194 This is text output or code.
195 # &lt;i&gt;this is user input&lt;/i&gt;
197 Make HTML/XML easier to read by using selective emphasis:
198 &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
200 &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
201 &lt;/pre&gt;
202 &lt;note&gt;This is a note.&lt;/note&gt;
203 &lt;warn&gt;This is a warning.&lt;/warn&gt;
204 &lt;impo&gt;This is important.&lt;/impo&gt;
205 </pre>
206 <p>Now, here's how this <c>&lt;body&gt;</c> element is rendered:</p>
208 <p>
209 This is a paragraph. <path>/etc/passwd</path> is a file.
210 <uri>http://www.gentoo.org</uri> is my favorite website.
211 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
212 </p>
214 <pre>
215 This is text output or code.
216 # <i>this is user input</i>
218 Make HTML/XML easier to read by using selective emphasis:
219 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
221 <codenote>This is how to insert an inline note into the code block</codenote>
222 </pre>
223 <note>This is a note.</note>
224 <warn>This is a warning.</warn>
225 <impo>This is important.</impo>
226 </body>
227 </section>
229 <section>
230 <title>The &lt;body&gt; tags</title>
231 <body>
233 <p> We introduced a lot of new tags in the previous section -- here's what you
234 need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
235 block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
236 <c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
237 Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
238 these are the only tags that should appear immediately inside a
239 <c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
240 stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
241 <c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
242 preserves its whitespace exactly, making it well-suited for code excerpts.</p>
244 </body>
245 </section>
246 <section>
247 <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
248 <body>
250 <p>The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
251 be used inside any child <c>&lt;body&gt;</c> tag, except for
252 <c>&lt;pre&gt;</c>. </p>
254 <p>The <c>&lt;path&gt;</c> element is used to mark text that refers to an
255 <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>.
256 This element is generally rendered with a monospaced font to offset it from the
257 standard paragraph type. </p>
259 <p>The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
260 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
261 that they can type in that will perform some kind of action. For example, all
262 the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
263 element because they represent something that the user could type in that is
264 not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
265 quickly identify commands that they need to type in. Also, because
266 <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
267 necessary to surround user input with double-quotes</e>. For example, don't
268 refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
269 the use of unnecessary double-quotes makes a document more readable -- and adorable!</p>
271 <p><c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
272 I <e>really</e> should use semicolons more often. As you can see, this text is
273 offset from the regular paragraph type for emphasis. This helps to give your
274 prose more <e>punch</e>!</p>
276 </body>
277 </section>
279 <section>
280 <title>&lt;mail&gt; and &lt;uri&gt;</title>
281 <body>
283 <p>We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link some text
284 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>
286 <p>The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
287 Internet. It has two forms -- the first can be used when you want to have the
288 actual URI displayed in the body text, such as this link to
289 <uri>http://www.gentoo.org</uri>. To create this link, I typed
290 <c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
291 when you want to associate a URI with some other text -- for example, <uri
292 link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e>
293 link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the Gentoo Linux website&lt;/uri&gt;</c>.
294 </p>
296 </body>
297 </section>
299 <section>
300 <title>Figures</title>
302 <body>
304 <p>Here's how to insert a figure into a document -- <c>&lt;figure
305 link="mygfx.png" short="my picture" caption="my favorite picture of all
306 time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
307 the <c>short=</c> attribute specifies a short description (currently used for
308 the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
309 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
310 for adding images without captions, borders, etc.</p>
312 </body>
313 </section>
314 <section>
315 <title>Tables and lists</title>
316 <body>
318 <p>Guide supports a simplified table syntax similar to that of HTML. To start
319 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
320 tag. However, for inserting actual table data, we <e>don't</e> support the
321 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
322 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
323 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> --
324 there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
325 first row. Currently, these tags don't support any attributes, but some will
326 be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
327 </p>
329 <p> To create ordered or unordered lists, simply use the HTML-style
330 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
331 should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
332 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag. </p>
334 </body>
335 </section>
337 <section>
338 <title>Intra-document references</title>
339 <body>
341 <p>Guide makes it really easy to reference other parts of the document using
342 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
343 One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
344 One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
345 Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
346 Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
347 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>,
348 type <c>&lt;uri link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
349 adding other auto-link abilities (such as table support) soon.</p>
351 </body>
352 </section>
353 </chapter>
354 <chapter>
355 <title>Resources</title>
356 <section>
357 <title>Start writing</title>
358 <body>
359 <p>Guide has been specially designed to be "lean and mean" so that developers
360 can spend more time writing documentation and less time learning the actual XML
361 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
362 to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please
363 post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail>
364 stating what you'd like to tackle.
365 Have fun!</p>
366 </body>
367 </section>
368 </chapter>
369 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20