/[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.7 - (hide annotations) (download) (as text)
Mon Jan 13 20:44:33 2003 UTC (11 years, 10 months ago) by zhen
Branch: MAIN
Changes since 1.6: +5 -0 lines
File MIME type: application/xml
added note about doc tarballs

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

  ViewVC Help
Powered by ViewVC 1.1.20