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

Parent Directory Parent Directory | Revision Log Revision Log

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

1 drobbins 1.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