/[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.64 - (hide annotations) (download) (as text)
Thu May 11 17:07:41 2006 UTC (8 years, 7 months ago) by rane
Branch: MAIN
Changes since 1.63: +5 -5 lines
File MIME type: application/xml
one can't mail gentoo-doc ML directly, switching to link to lists.xml file instead

1 cam 1.41 <?xml version="1.0" encoding="UTF-8"?>
2 rane 1.64 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.63 2006/05/07 14:41:19 rane Exp $ -->
3 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 zhen 1.2 <guide link="/doc/en/xml-guide.xml">
6 vapier 1.50 <title>Gentoo XML Guide</title>
7 swift 1.15
8     <author title="Author">
9 neysx 1.58 <mail link="neysx@gentoo.org">Xavier Neys</mail>
10     </author>
11     <author title="Author">
12 swift 1.15 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13     </author>
14 swift 1.19 <author title="Author"><!-- zhen@gentoo.org -->
15     John P. Davis
16 swift 1.15 </author>
17     <author title="Editor">
18     <mail link="peesh@gentoo.org">Jorge Paulo</mail>
19     </author>
20 swift 1.25 <author title="Editor">
21     <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22     </author>
23 drobbins 1.1
24 swift 1.15 <abstract>
25     This guide shows you how to compose web documentation using the new lightweight
26 vapier 1.50 Gentoo GuideXML syntax. This syntax is the official format for Gentoo
27 swift 1.15 documentation, and this document itself was created using GuideXML. This guide
28     assumes a basic working knowledge of XML and HTML.
29 drobbins 1.1 </abstract>
30    
31 swift 1.31 <!-- The content of this document is licensed under the CC-BY-SA license -->
32 swift 1.46 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33 swift 1.26 <license/>
34    
35 rane 1.64 <version>7</version>
36     <date>2006-05-11</date>
37 drobbins 1.1
38     <chapter>
39     <title>Guide basics</title>
40     <section>
41     <title>Guide XML design goals</title>
42     <body>
43    
44 swift 1.15 <p>
45     The guide XML syntax is lightweight yet expressive, so that it is easy to
46 drobbins 1.1 learn yet also provides all the features we need for the creation of web
47     documentation. The number of tags is kept to a minimum -- just those we need.
48     This makes it easy to transform guide into other formats, such as DocBook
49 swift 1.15 XML/SGML or web-ready HTML.
50     </p>
51 drobbins 1.1
52 swift 1.15 <p>
53     The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
54     documents.
55     </p>
56 drobbins 1.1
57     </body>
58     </section>
59     <section>
60 swift 1.20 <title>Further Resources</title>
61 drobbins 1.1 <body>
62    
63 swift 1.15 <p>
64 neysx 1.34 If you are planning on contributing documentation to Gentoo, or you want to
65 neysx 1.52 test GuideXML, please read our <uri
66     link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
67     which contains tips and tricks for documentation development.
68     </p>
69    
70     <p>
71     You may want to look at the <uri link="?passthru=1">XML source</uri> of this
72     document while you read it.
73 drobbins 1.1 </p>
74    
75     </body>
76     </section>
77     </chapter>
78 swift 1.15
79 drobbins 1.1 <chapter>
80 swift 1.15 <title>Guide XML</title>
81 drobbins 1.1 <section>
82     <title>Basic structure</title>
83     <body>
84    
85 swift 1.15 <p>
86 swift 1.36 Let's start learning the GuideXML syntax. We'll start with the the initial
87     tags used in a GuideXML document:
88 swift 1.15 </p>
89 drobbins 1.1
90     <pre caption="The initial part of a guide XML document">
91 cam 1.41 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
92 swift 1.25 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
93 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
94    
95 neysx 1.43 &lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt;
96 vapier 1.50 &lt;title&gt;<i>Gentoo Documentation Guide</i>&lt;/title&gt;
97 neysx 1.49
98 swift 1.33 &lt;author title="<i>Author</i>"&gt;
99     &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
100 drobbins 1.1 &lt;/author&gt;
101    
102 swift 1.15 &lt;abstract&gt;
103     <i>This guide shows you how to compose web documentation using
104     our new lightweight Gentoo GuideXML syntax. This syntax is the official
105 vapier 1.50 format for Gentoo web documentation, and this document itself was created
106 swift 1.15 using GuideXML.</i>
107     &lt;/abstract&gt;
108 drobbins 1.1
109 swift 1.27 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
110 swift 1.46 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
111 swift 1.14 &lt;license/&gt;
112    
113 drobbins 1.1 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
114 neysx 1.35 &lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
115 drobbins 1.1 </pre>
116    
117 swift 1.15 <p>
118 neysx 1.42 On the first lines, we see the requisite tag that identifies this as an XML
119     document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
120     will be automatically modified by the CVS server and helps to track revisions.
121 neysx 1.51 Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
122     enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c>
123 neysx 1.43 attribute is compulsory and should preferably contain the absolute path to the
124     document relatively to the document root even though the file name alone will
125     work. It is mainly used to generate a link to a printer-friendly version of
126 neysx 1.51 your document. If you use a wrong value, the link to the printable version will
127     either not work or point to a wrong document. Translated documents <e>must</e>
128     specify the full path because it is also used to check whether a more recent
129     original document exists. The <c>lang</c> attribute should be used to specify
130     the language code of your document. It is used to format the date and insert
131     strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language.
132     The default is English.
133 neysx 1.35 </p>
134    
135     <p>
136 drobbins 1.1 Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
137 swift 1.15 guide document.
138     </p>
139 drobbins 1.1
140 swift 1.15 <p>
141     Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
142 drobbins 1.1 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
143 neysx 1.52 allows for an optional <c>title</c> element, used to specify the author's
144 drobbins 1.1 relationship to the document (author, co-author, editor, etc.). In this
145     particular example, the authors' names are enclosed in another tag -- a
146     <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
147     person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
148     more than one <c>&lt;author&gt;</c> element is required per guide document.
149     </p>
150    
151 swift 1.15 <p>
152     Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
153 drobbins 1.1 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
154 neysx 1.35 current version number, and the current version date (in YYYY-MM-DD format)
155     respectively. Dates that are invalid or not in the YYYY-MM-DD format will
156     appear verbatim in the rendered document.
157     </p>
158    
159     <p>
160     This rounds out the tags that should appear at the beginning of a guide
161     document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these
162     tags shouldn't appear anywhere else except immediately inside the
163 drobbins 1.1 <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
164 swift 1.15 required) that these tags appear before the content of the document.
165     </p>
166 swift 1.14
167 swift 1.15 <p>
168 neysx 1.38 Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document
169 neysx 1.49 under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
170 neysx 1.38 Commons - Attribution / Share Alike</uri> license as required by the <uri
171     link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
172 swift 1.15 </p>
173 drobbins 1.1
174     </body>
175     </section>
176     <section>
177     <title>Chapters and sections</title>
178     <body>
179 swift 1.15
180     <p>
181 neysx 1.37 Once the initial tags have been specified, you're ready to start adding the
182     structural elements of the document. Guide documents are divided into
183     chapters, and each chapter can hold one or more sections. Every chapter and
184     section has a title. Here's an example chapter with a single section,
185     consisting of a paragraph. If you append this XML to the XML in the <uri
186     link="#doc_chap2_pre1">previous excerpt</uri> and append a
187     <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid (if minimal)
188     guide document:
189 drobbins 1.1 </p>
190    
191 neysx 1.37 <pre caption="Minimal guide example">
192 drobbins 1.1 &lt;chapter&gt;
193     &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
194     &lt;section&gt;
195 swift 1.15 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
196     &lt;body&gt;
197    
198     &lt;p&gt;
199     <i>This is the actual text content of my section.</i>
200     &lt;/p&gt;
201    
202     &lt;/body&gt;
203 drobbins 1.1 &lt;/section&gt;
204     &lt;/chapter&gt;
205     </pre>
206    
207 swift 1.15 <p>
208     Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
209 drobbins 1.1 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
210     adding a <c>&lt;section&gt;</c> element. If you look inside the
211     <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
212     <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
213     is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
214     content of this particular section. We'll look at the tags that are allowed
215 swift 1.15 inside a <c>&lt;body&gt;</c> element in a bit.
216     </p>
217 drobbins 1.1
218 swift 1.15 <note>
219     A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
220     elements, and a <c>&lt;chapter&gt;</c> can contain multiple
221     <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
222     element can only contain one <c>&lt;body&gt;</c> element.
223     </note>
224 drobbins 1.1
225     </body>
226     </section>
227     <section>
228     <title>An example &lt;body&gt;</title>
229     <body>
230 swift 1.15
231 drobbins 1.1 <p>
232 neysx 1.37 Now, it's time to learn how to mark up actual content. Here's the XML code for
233     an example <c>&lt;body&gt;</c> element:
234 drobbins 1.1 </p>
235 swift 1.15
236 neysx 1.37 <pre caption="Example of a body element">
237 drobbins 1.1 &lt;p&gt;
238     This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
239 neysx 1.35 &lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
240 drobbins 1.1 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.
241     &lt;/p&gt;
242    
243 neysx 1.37 &lt;pre caption="Code Sample"&gt;
244 drobbins 1.1 This is text output or code.
245     # &lt;i&gt;this is user input&lt;/i&gt;
246    
247     Make HTML/XML easier to read by using selective emphasis:
248     &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
249    
250 neysx 1.58 &lt;comment&gt;(This is how to insert a comment into a code block)&lt;/comment&gt;
251 drobbins 1.1 &lt;/pre&gt;
252 swift 1.15
253     &lt;note&gt;
254     This is a note.
255     &lt;/note&gt;
256    
257     &lt;warn&gt;
258     This is a warning.
259     &lt;/warn&gt;
260    
261     &lt;impo&gt;
262     This is important.
263     &lt;/impo&gt;
264 drobbins 1.1 </pre>
265 swift 1.15
266     <p>
267 neysx 1.37 Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
268 swift 1.15 </p>
269 drobbins 1.1
270     <p>
271     This is a paragraph. <path>/etc/passwd</path> is a file.
272 swift 1.45 <uri>http://forums.gentoo.org</uri> is my favorite web site.
273 drobbins 1.1 Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
274     </p>
275    
276 neysx 1.37 <pre caption="Code Sample">
277 drobbins 1.1 This is text output or code.
278     # <i>this is user input</i>
279    
280     Make HTML/XML easier to read by using selective emphasis:
281     &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
282    
283 neysx 1.58 <comment>(This is how to insert a comment into a code block)</comment>
284 drobbins 1.1 </pre>
285 swift 1.15
286     <note>
287     This is a note.
288     </note>
289    
290     <warn>
291     This is a warning.
292     </warn>
293    
294     <impo>
295     This is important.
296     </impo>
297    
298 drobbins 1.1 </body>
299     </section>
300     <section>
301     <title>The &lt;body&gt; tags</title>
302     <body>
303    
304 swift 1.15 <p>
305 neysx 1.52 We introduced a lot of new tags in the previous section -- here's what you need
306     to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block),
307     <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and <c>&lt;impo&gt;</c>
308     (important) tags all can contain one or more lines of text. Besides the
309     <c>&lt;table&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and
310     <c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
311     only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
312     Another thing -- these tags <e>should not</e> be stacked -- in other words,
313     don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
314     you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
315     exactly, making it well-suited for code excerpts. You must name the
316 neysx 1.53 <c>&lt;pre&gt;</c> tag with a <c>caption</c> attribute:
317 swift 1.15 </p>
318 swift 1.12
319 neysx 1.37 <pre caption="Named &lt;pre&gt;">
320 neysx 1.51 &lt;pre caption="Output of uptime"&gt;
321 swift 1.12 # &lt;i&gt;uptime&lt;/i&gt;
322     16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
323     &lt;/pre&gt;
324     </pre>
325 drobbins 1.1
326     </body>
327     </section>
328     <section>
329 neysx 1.52 <title>Epigraphs</title>
330     <body>
331    
332     <p by="Anonymous student">
333     Delegates from the original 13 states formed the Contented Congress. Thomas
334     Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
335     of Independence. Franklin discovered electricity by rubbing two cats backwards
336     and declared, "A horse divided against itself cannot stand." Franklin died in
337     1790 and is still dead.
338     </p>
339    
340     <p>
341     Epigraphs are sometimes used at the beginning of chapters to illustrate what is
342     to follow. It is simply a paragraph with a <c>by</c> attribute that contains
343     the signature.
344     </p>
345    
346     <pre caption="Short epigraph">
347     &lt;p by="Anonymous student"&gt;
348     Delegates from the original 13 states formed the...
349     &lt;/p&gt;
350     </pre>
351    
352     </body>
353     </section>
354     <section>
355     <title>
356 neysx 1.58 &lt;path&gt;, &lt;c&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
357 neysx 1.52 </title>
358 drobbins 1.1 <body>
359    
360 swift 1.15 <p>
361 neysx 1.52 The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
362     <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
363 neysx 1.58 <c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>.
364 swift 1.15 </p>
365 drobbins 1.1
366 swift 1.15 <p>
367     The <c>&lt;path&gt;</c> element is used to mark text that refers to an
368     <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
369 swift 1.45 <e>simple filename</e>. This element is generally rendered with a mono spaced
370 swift 1.15 font to offset it from the standard paragraph type.
371     </p>
372 drobbins 1.1
373 swift 1.15 <p>
374     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
375 drobbins 1.1 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
376     that they can type in that will perform some kind of action. For example, all
377     the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
378     element because they represent something that the user could type in that is
379     not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
380     quickly identify commands that they need to type in. Also, because
381     <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
382     necessary to surround user input with double-quotes</e>. For example, don't
383     refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
384 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
385     adorable!
386     </p>
387 drobbins 1.1
388 swift 1.15 <p>
389 neysx 1.51 As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some
390     text.
391     </p>
392    
393     <p>
394 swift 1.15 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
395 drobbins 1.1 I <e>really</e> should use semicolons more often. As you can see, this text is
396     offset from the regular paragraph type for emphasis. This helps to give your
397 swift 1.15 prose more <e>punch</e>!
398     </p>
399 drobbins 1.1
400 neysx 1.52 <p>
401     The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
402     <sub>subscript</sub> and <sup>superscript</sup>.
403     </p>
404    
405 drobbins 1.1 </body>
406     </section>
407     <section>
408 neysx 1.58 <title>Code samples and colour-coding</title>
409     <body>
410    
411     <p>
412     To improve the readability of code samples, the following tags are allowed
413     inside <c>&lt;pre&gt;</c> blocks:
414     </p>
415    
416     <dl>
417     <dt><c>&lt;i&gt;</c></dt>
418     <dd>Distinguishes user input from displayed text</dd>
419     <dt><c>&lt;comment&gt;</c></dt>
420     <dd>Comments relevant to the action(s) that appear after the comment</dd>
421     <dt><c>&lt;keyword&gt;</c></dt>
422     <dd>Denotes a keyword in the language used in the code sample
423     </dd>
424     <dt><c>&lt;ident&gt;</c></dt>
425     <dd>Used for an identifier
426     </dd>
427     <dt><c>&lt;const&gt;</c></dt>
428     <dd>Used for a constant
429     </dd>
430     <dt><c>&lt;stmt&gt;</c></dt>
431     <dd>Used for a statement
432     </dd>
433     <dt><c>&lt;var&gt;</c></dt>
434     <dd>Used for a variable
435     </dd>
436     </dl>
437    
438     <note>
439     Remember that all leading and trailing spaces, and line breaks in
440     <c>&lt;pre&gt;</c> blocks will appear in the displayed html page.
441     </note>
442    
443     <p>
444     Sample colour-coded <c>&lt;pre&gt;</c> block:
445     </p>
446    
447     <pre caption="My first ebuild">
448     <comment># Copyright 1999-2006 <b>Gentoo Foundation</b>
449     # Distributed under the terms of the GNU General Public License v2
450     # &#36;Header: $</comment>
451    
452     <ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
453     <ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
454     <ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
455    
456     <ident>LICENSE</ident>=<const>"GPL-2"</const>
457     <ident>SLOT</ident>=<const>"0"</const>
458     <ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
459     <ident>IUSE</ident>=<const>""</const>
460    
461     <stmt>src_compile()</stmt> {
462     <keyword>econf</keyword> --with-posix-regex || <keyword>die</keyword> <const>"econf failed"</const>
463     <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const>
464     }
465    
466     <stmt>src_install()</stmt> {
467     <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const>
468    
469     <keyword>dodoc</keyword> FAQ NEWS README
470     <keyword>dohtml</keyword> EXTENDING.html ctags.html
471     }
472     </pre>
473    
474     </body>
475     </section>
476     <section>
477 drobbins 1.1 <title>&lt;mail&gt; and &lt;uri&gt;</title>
478     <body>
479    
480 swift 1.15 <p>
481 neysx 1.51 We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
482     some text with a particular email address, and takes the form <c>&lt;mail
483     link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the
484     email address, you can use <c>&lt;mail&gt;foo@bar.com&lt;/mail&gt;</c>, this
485     would be displayed as <mail>foo@bar.com</mail>.
486 swift 1.15 </p>
487 drobbins 1.1
488 swift 1.15 <p>
489 neysx 1.35 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
490     It has two forms -- the first can be used when you want to have the actual URI
491     displayed in the body text, such as this link to
492     <uri>http://forums.gentoo.org</uri>. To create this link, I typed
493     <c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
494 drobbins 1.1 when you want to associate a URI with some other text -- for example, <uri
495 neysx 1.35 link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
496     link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
497     Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
498 swift 1.45 to link to other parts of the Gentoo web site. For instance, a link to the <uri
499 neysx 1.35 link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
500     link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
501     even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
502     link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
503 drobbins 1.1 </p>
504    
505     </body>
506     </section>
507     <section>
508     <title>Figures</title>
509     <body>
510    
511 swift 1.15 <p>
512     Here's how to insert a figure into a document -- <c>&lt;figure
513 drobbins 1.1 link="mygfx.png" short="my picture" caption="my favorite picture of all
514 neysx 1.52 time"/&gt;</c>. The <c>link</c> attribute points to the actual graphic image,
515     the <c>short</c> attribute specifies a short description (currently used for
516     the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
517 drobbins 1.1 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
518 swift 1.15 for adding images without captions, borders, etc.
519     </p>
520 drobbins 1.1
521     </body>
522     </section>
523     <section>
524 neysx 1.52 <title>Tables</title>
525 drobbins 1.1 <body>
526    
527 swift 1.15 <p>
528 neysx 1.52 Guide supports a simplified table syntax similar to that of HTML. To start a
529 neysx 1.51 table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
530 neysx 1.52 tag. However, for inserting actual table data, we <e>don't</e> support the
531 drobbins 1.1 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
532     header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
533 neysx 1.51 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
534     -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
535     first row.
536 drobbins 1.1 </p>
537    
538 swift 1.15 <p>
539 neysx 1.60 Besides, both table headers (<c>&lt;th&gt;</c>) and table items
540     (<c>&lt;ti&gt;</c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to
541 neysx 1.61 span their content across rows, columns or both.
542     </p>
543    
544     <p>
545     Furthermore, table items (<c>&lt;ti&gt;</c>) can be right-aligned or centered
546     with the <c>align</c> attribute. Table headers (<c>&lt;th&gt;</c>) are
547     automatically centered.
548 neysx 1.52 </p>
549    
550     <table>
551     <tr>
552     <th colspan="4">This title spans 4 columns</th>
553     </tr>
554     <tr>
555 neysx 1.59 <th rowspan="6">This title spans 6 rows</th>
556 neysx 1.52 <ti>Item A1</ti>
557     <ti>Item A2</ti>
558     <ti>Item A3</ti>
559     </tr>
560     <tr>
561 neysx 1.61 <ti align="center">Item B1</ti>
562 neysx 1.52 <th colspan="2" rowspan="2">Blocky 2x2 title</th>
563     </tr>
564     <tr>
565 neysx 1.61 <ti align="right">Item C1</ti>
566 neysx 1.52 </tr>
567 neysx 1.59 <tr>
568 neysx 1.61 <ti colspan="3" align="center">Item D1..D3</ti>
569 neysx 1.59 </tr>
570     <tr>
571     <ti rowspan="2">Item E1..F1</ti>
572 neysx 1.61 <ti colspan="2" align="right">Item E2..E3</ti>
573 neysx 1.59 </tr>
574     <tr>
575 neysx 1.61 <ti colspan="2" align="right">Item F2..F3</ti>
576 neysx 1.59 </tr>
577 neysx 1.52 </table>
578    
579     </body>
580     </section>
581     <section>
582     <title>Lists</title>
583     <body>
584    
585     <p>
586 swift 1.39 To create ordered or unordered lists, simply use the XHTML-style
587 neysx 1.52 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
588     appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
589     that you can have lists inside lists. Don't forget that you are writing XML and
590     that you must close all tags including list items unlike in HTML.
591 swift 1.15 </p>
592 drobbins 1.1
593 neysx 1.52 <p>
594     Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that
595     neither the definition term tag (<c>&lt;dt&gt;</c>) nor the definition data tag
596     (<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
597 neysx 1.53 admonitions. A definition list comprises:
598 neysx 1.52 </p>
599    
600     <dl>
601     <dt><c>&lt;dl&gt;</c></dt>
602     <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
603     <dt><c>&lt;dt&gt;</c></dt>
604     <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
605     <dt><c>&lt;dd&gt;</c></dt>
606     <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
607     </dl>
608    
609     <p>
610     The following list copied from <uri
611     link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
612     that a definition list can contain ordered and unordered lists. It may not
613     contain another definition list though.
614     </p>
615    
616     <dl>
617     <dt><b>The ingredients:</b></dt>
618     <dd>
619     <ul>
620     <li>100 g. flour</li>
621     <li>10 g. sugar</li>
622     <li>1 cup water</li>
623     <li>2 eggs</li>
624     <li>salt, pepper</li>
625     </ul>
626     </dd>
627     <dt><b>The procedure:</b></dt>
628     <dd>
629     <ol>
630 neysx 1.53 <li>Mix dry ingredients thoroughly</li>
631     <li>Pour in wet ingredients</li>
632     <li>Mix for 10 minutes</li>
633     <li>Bake for one hour at 300 degrees</li>
634 neysx 1.52 </ol>
635     </dd>
636     <dt><b>Notes:</b></dt>
637 neysx 1.53 <dd>The recipe may be improved by adding raisins</dd>
638 neysx 1.52 </dl>
639    
640 drobbins 1.1 </body>
641     </section>
642     <section>
643     <title>Intra-document references</title>
644     <body>
645    
646 swift 1.15 <p>
647     Guide makes it really easy to reference other parts of the document using
648 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
649     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
650     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
651     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
652     Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
653 swift 1.40 link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
654 swift 1.15 link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
655 neysx 1.52 link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.
656 swift 1.17 </p>
657 swift 1.23
658     <p>
659     However, some guides change often and using such "counting" can lead to broken
660     links. In order to cope with this, you can define a name for a
661 neysx 1.47 <c>&lt;chapter&gt;</c>, <c>&lt;section&gt;</c> or a <c>&lt;tr&gt;</c> by using
662     the <c>id</c> attribute, and then point to that attribute, like this:
663 swift 1.23 </p>
664    
665     <pre caption="Using the id attribute">
666     &lt;chapter id="foo"&gt;
667     &lt;title&gt;This is foo!&lt;/title&gt;
668     ...
669     &lt;p&gt;
670     More information can be found in the &lt;uri link="#foo"&gt;foo chapter&lt;/uri&gt;
671     &lt;/p&gt;
672     </pre>
673 swift 1.17
674     </body>
675     </section>
676 neysx 1.51 <section>
677     <title>Disclaimers and obsolete documents</title>
678     <body>
679    
680     <p>
681 alin 1.54 A <c>disclaimer</c> attribute can be applied to guides and handbooks to display
682     a predefined disclaimer at the top of the document. The available disclaimers
683     are:
684 neysx 1.51 </p>
685    
686     <ul>
687     <li>
688     <b>articles</b> is used for <uri link="/doc/en/articles/">republished
689     articles</uri>
690     </li>
691     <li>
692     <b>draft</b> is used to indicate a document is still being worked on and
693     should not be considered official
694     </li>
695     <li>
696     <b>oldbook</b> is used on old handbooks to indicate they are not maintained
697     anymore
698     </li>
699     <li><b>obsolete</b> is used to mark a document as obsolete.</li>
700     </ul>
701    
702     <p>
703     When marking a document as obsolete, you might want to add a link to a new
704     version. The <c>redirect</c> attribute does just that. The user might be
705     automatically redirected to the new page but you should not rely on that
706     behaviour.
707     </p>
708    
709     <pre caption="Disclaimer sample">
710     &lt;?xml version="1.0" encoding="UTF-8"?&gt;
711     &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
712     &lt;!-- &#36;Header&#36; --&gt;
713    
714     &lt;guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
715     &lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
716    
717     &lt;author title="Author"&gt;
718     ...
719     </pre>
720    
721     </body>
722     </section>
723 swift 1.17 </chapter>
724    
725     <chapter>
726     <title>Coding Style</title>
727     <section>
728     <title>Introduction</title>
729     <body>
730    
731     <p>
732     Since all Gentoo Documentation is a joint effort and several people will
733     most likely change existing documentation, a coding style is needed.
734     A coding style contains two sections. The first one is regarding
735 swift 1.45 internal coding - how the XML-tags are placed. The second one is
736 swift 1.17 regarding the content - how not to confuse the reader.
737     </p>
738    
739     <p>
740     Both sections are described next.
741     </p>
742    
743     </body>
744     </section>
745     <section>
746     <title>Internal Coding Style</title>
747     <body>
748    
749     <p>
750     <b>Newlines</b> must be placed immediately after <e>every</e>
751     GuideXML-tag (both opening as closing), except for:
752     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
753     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
754     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
755 swift 1.44 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
756 neysx 1.37 <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
757 swift 1.17 </p>
758    
759     <p>
760     <b>Blank lines</b> must be placed immediately after <e>every</e>
761     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
762     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
763 swift 1.18 <c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
764     <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
765     <c>&lt;impo&gt;</c> (opening tags only).
766 swift 1.17 </p>
767    
768     <p>
769     <b>Word-wrapping</b> must be applied at 80 characters except inside
770 neysx 1.51 <c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
771     choice (for instance when a URL exceeds the maximum amount of characters). The
772     editor must then wrap whenever the first whitespace occurs. You should try to
773     keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
774     columns to help console users.
775 swift 1.17 </p>
776    
777     <p>
778 neysx 1.51 <b>Indentation</b> may not be used, except with the XML-constructs of which the
779     parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
780 neysx 1.53 <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>, <c>&lt;dl&gt;</c>, and
781     <c>&lt;author&gt;</c>. If indentation is used, it <e>must</e> be two spaces for
782     each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
783     Besides, tabs are not allowed in GuideXML documents.
784 swift 1.17 </p>
785    
786     <p>
787 neysx 1.53 In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>,
788 neysx 1.57 <c>&lt;li&gt;</c> or <c>&lt;dd&gt;</c> constructs, indentation must be used for
789 neysx 1.53 the content.
790 swift 1.17 </p>
791    
792     <p>
793     An example for indentation is:
794     </p>
795    
796 neysx 1.37 <pre caption="Indentation Example">
797 swift 1.17 &lt;table&gt;
798     &lt;tr&gt;
799     &lt;th&gt;Foo&lt;/th&gt;
800     &lt;th&gt;Bar&lt;/th&gt;
801     &lt;/tr&gt;
802     &lt;tr&gt;
803 swift 1.48 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
804 swift 1.17 &lt;ti&gt;
805     In case text cannot be shown within an 80-character wide line, you
806 swift 1.48 must use indentation if the parent tag allows it
807 swift 1.17 &lt;/ti&gt;
808     &lt;/tr&gt;
809     &lt;/table&gt;
810    
811     &lt;ul&gt;
812     &lt;li&gt;First option&lt;/li&gt;
813     &lt;li&gt;Second option&lt;/li&gt;
814     &lt;/ul&gt;
815     </pre>
816    
817     <p>
818 neysx 1.53 <b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
819     and the attribute value. As an example:
820 swift 1.17 </p>
821    
822     <pre caption="Attributes">
823     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
824     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
825     </pre>
826    
827     </body>
828     </section>
829     <section>
830     <title>External Coding Style</title>
831     <body>
832    
833     <p>
834 neysx 1.53 Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c>,
835     <c>&lt;ol&gt;</c>) and <c>&lt;dl&gt;</c>, periods (".") should not be used
836     unless multiple sentences are used. In that case, every sentence should end
837     with a period (or other reading marks).
838 swift 1.17 </p>
839    
840     <p>
841     Every sentence, including those inside tables and listings, should start
842     with a capital letter.
843     </p>
844    
845     <pre caption="Periods and capital letters">
846     &lt;ul&gt;
847     &lt;li&gt;No period&lt;/li&gt;
848     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
849     &lt;/ul&gt;
850     </pre>
851    
852     <p>
853     Code Listings should <e>always</e> have a <c>caption</c>.
854     </p>
855    
856     <p>
857     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
858 neysx 1.35 possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
859     Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
860 swift 1.15 </p>
861 swift 1.18
862     <p>
863 neysx 1.37 When you comment something inside a <c>&lt;pre&gt;</c> construct, use
864     <c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
865     that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
866     for C code, etc.) Also place the comment <e>before</e> the subject of the
867     comment.
868 swift 1.18 </p>
869    
870     <pre caption="Comment example">
871     <comment>(Substitute "john" with your user name)</comment>
872     # <i>id john</i>
873     </pre>
874 drobbins 1.1
875     </body>
876     </section>
877     </chapter>
878 swift 1.15
879 drobbins 1.1 <chapter>
880 swift 1.25 <title>Handbook Format</title>
881     <section>
882     <title>Guide vs Book</title>
883     <body>
884    
885     <p>
886     For high-volume documentation, such as the <uri
887 neysx 1.29 link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
888 swift 1.25 broader format was needed. We designed a GuideXML-compatible enhancement that
889     allows us to write modular and multi-page documentation.
890     </p>
891    
892     </body>
893     </section>
894     <section>
895     <title>Main File</title>
896     <body>
897    
898     <p>
899     The first change is the need for a "master" document. This document contains no
900 rane 1.63 real content, but links to the individual documentation modules. The syntax
901 swift 1.25 doesn't differ much from GuideXML:
902     </p>
903    
904     <pre caption="Example book usage">
905     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
906     &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
907 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
908 swift 1.25
909     &lt;<i>book</i> link="example.xml"&gt;
910     &lt;title&gt;Example Book Usage&lt;/title&gt;
911    
912     &lt;author...&gt;
913     ...
914     &lt;/author&gt;
915    
916     &lt;abstract&gt;
917     ...
918     &lt;/abstract&gt;
919    
920     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
921 neysx 1.49 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
922 swift 1.25 &lt;license/&gt;
923    
924     &lt;version&gt;...&lt;/version&gt;
925     &lt;date&gt;...&lt;/date&gt;
926     </pre>
927    
928     <p>
929     So far no real differences (except for the <c>&lt;book&gt;</c> instead of
930     <c>&lt;guide&gt;</c> tag). Instead of starting with the individual
931 neysx 1.56 <c>&lt;chapter&gt;</c>s, you define a <c>&lt;part&gt;</c>, which is the
932 swift 1.25 equivalent of a separate part in a book:
933     </p>
934    
935     <pre caption="Defining a part">
936     &lt;part&gt;
937     &lt;title&gt;Part One&lt;/title&gt;
938     &lt;abstract&gt;
939     ...
940     &lt;/abstract&gt;
941    
942     <comment>(Defining the several chapters)</comment>
943     &lt;/part&gt;
944     </pre>
945    
946     <p>
947     Each part is accompanied by a <c>&lt;title&gt;</c> and an
948     <c>&lt;abstract&gt;</c> which gives a small introduction to the part.
949     </p>
950    
951     <p>
952 neysx 1.56 Inside each part, you define the individual <c>&lt;chapter&gt;</c>s. Each
953     chapter <e>must</e> be a separate document. As a result it is no surprise that
954     a special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
955 swift 1.25 document.
956     </p>
957    
958     <pre caption="Defining a chapter">
959     &lt;chapter&gt;
960     &lt;title&gt;Chapter One&lt;/title&gt;
961     &lt;abstract&gt;
962     This is a small explanation on chapter one.
963     &lt;/abstract&gt;
964    
965     &lt;include href="path/to/chapter-one.xml"/&gt;
966    
967     &lt;/chapter&gt;
968     </pre>
969    
970     </body>
971     </section>
972     <section>
973     <title>Designing the Individual Chapters</title>
974     <body>
975    
976     <p>
977     The content of an individual chapter is structured as follows:
978     </p>
979    
980     <pre caption="Chapter Syntax">
981     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
982     &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
983 neysx 1.42 &lt;!-- &#36;Header&#36; --&gt;
984 swift 1.25
985     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
986 neysx 1.49 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
987 swift 1.25
988     &lt;sections&gt;
989    
990 neysx 1.35 &lt;version&gt;...&lt;/version&gt;
991     &lt;date&gt;...&lt;/date&gt;
992    
993 swift 1.25 <comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
994    
995     &lt;/sections&gt;
996     </pre>
997    
998     <p>
999 neysx 1.56 Inside each chapter you can define <c>&lt;section&gt;</c>s (equivalent of
1000     <c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>s (equivalent
1001 swift 1.25 of <c>&lt;section&gt;</c> in a Guide).
1002     </p>
1003    
1004 neysx 1.35 <p>
1005     Each individual chapter should have its own date and version elements. The
1006     latest date of all chapters and master document will be displayed when a user
1007     browses through all parts of the book.
1008     </p>
1009    
1010 swift 1.25 </body>
1011     </section>
1012     </chapter>
1013    
1014     <chapter>
1015 drobbins 1.1 <title>Resources</title>
1016     <section>
1017 swift 1.15 <title>Start writing</title>
1018     <body>
1019    
1020     <p>
1021 neysx 1.35 Guide has been specially designed to be "lean and mean" so that developers can
1022     spend more time writing documentation and less time learning the actual XML
1023 swift 1.15 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
1024 vapier 1.50 to start writing quality Gentoo documentation. You might be interested
1025 neysx 1.35 in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation
1026     Development Tips &amp; Tricks</uri>. If you'd like to help (or have any
1027 rane 1.64 questions about guide), please post a message to the <uri
1028     link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd
1029 neysx 1.55 like to tackle. Have fun!
1030 swift 1.15 </p>
1031    
1032     </body>
1033 drobbins 1.1 </section>
1034     </chapter>
1035     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20