/[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.17 - (hide annotations) (download) (as text)
Tue Oct 14 18:34:08 2003 UTC (10 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.16: +141 -12 lines
File MIME type: application/xml
Add coding style

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 zhen 1.9 <title>Gentoo Linux XML Guide</title>
6 swift 1.15
7     <author title="Author">
8     <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
9     </author>
10     <author title="Author">
11     <mail link="zhen@gentoo.org">John P. Davis</mail>
12     </author>
13     <author title="Editor">
14     <mail link="peesh@gentoo.org">Jorge Paulo</mail>
15     </author>
16 drobbins 1.1
17 swift 1.13 <license/>
18 swift 1.15 <abstract>
19     This guide shows you how to compose web documentation using the new lightweight
20     Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21     documentation, and this document itself was created using GuideXML. This guide
22     assumes a basic working knowledge of XML and HTML.
23 drobbins 1.1 </abstract>
24    
25 swift 1.17 <version>2.1</version>
26     <date>October 14, 2003</date>
27 drobbins 1.1
28     <chapter>
29     <title>Guide basics</title>
30     <section>
31     <title>Guide XML design goals</title>
32     <body>
33    
34 swift 1.15 <p>
35     The guide XML syntax is lightweight yet expressive, so that it is easy to
36 drobbins 1.1 learn yet also provides all the features we need for the creation of web
37     documentation. The number of tags is kept to a minimum -- just those we need.
38     This makes it easy to transform guide into other formats, such as DocBook
39 swift 1.15 XML/SGML or web-ready HTML.
40     </p>
41 drobbins 1.1
42 swift 1.15 <p>
43     The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
44     documents.
45     </p>
46 drobbins 1.1
47     </body>
48     </section>
49     <section>
50     <title>How to transform guide XML into HTML</title>
51     <body>
52    
53 swift 1.15 <p>
54     Before we take a look at the guide syntax itself, it's helpful to know how
55 drobbins 1.1 guide XML is transformed into web-ready HTML. To do this, we use a special
56 zhen 1.6 file called <path>guide.xsl</path>, along with a command-line XSLT processing
57     tool (also called an "engine"). The <path>guide.xsl</path> file describes
58 drobbins 1.1 exactly how to transform the contents of the source guide XML document to
59 zhen 1.9 create the target HTML file. The processing tool that Gentoo Linux uses
60 swift 1.15 is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
61     </p>
62 zhen 1.6
63 zhen 1.9 <pre caption="Installing libxslt">
64 swift 1.17 # <i>emerge libxslt</i>
65 zhen 1.9 </pre>
66 zhen 1.6
67 swift 1.15 <p>
68     Now that we have the way, we need the means, so to speak. In other words,
69 zhen 1.9 we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
70 swift 1.15 that are available for download:
71     </p>
72 zhen 1.9
73 swift 1.15 <p>
74     <b>The first type contains the entire up-to-date Gentoo Linux website</b>.
75     Included are our XSL templates, so if you are planning to transform any
76     documentation, you will need this tarball. The tarball can be found <uri
77     link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
78     </p>
79    
80     <p>
81     <b>The second type contains daily snapshots our XML documentation source</b>
82     in every language that we offer. Please note that it is impossible to transform
83     documentation with this tarball, so please download the web tarball if you want
84     to fully develop your own documentation. These tarballs are especially useful
85     for translators. These tarballs can be found <uri
86     link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
87     </p>
88    
89     <p>
90     After the web tarball is downloaded and extracted, go to the directory where
91     the tarball was extracted, and enter the <path>htdocs</path> directory. Browse
92     around and get comfortable with the layout, but note the <path>xsl</path> and
93     <path>doc</path> directories. As you might have guessed, the XSL stylesheets are
94     in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing
95     purposes, we will be using the Gentoo Linux CD Installation Guide, located at
96     <path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL
97     and XML file are known, we can do some transforming with <c>xsltproc</c>.
98     </p>
99 zhen 1.6
100     <pre caption="Transforming gentoo-x86-install.xml">
101 swift 1.17 # <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</i>
102 drobbins 1.1 </pre>
103    
104 swift 1.15 <p>
105     If all went well, you should have a web-ready version of
106     <path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For
107     this document to display properly in a web browser, you may have to copy some
108     files from <path>htdocs</path> to <path>/tmp</path>, such as
109     <path>css/main.css</path> and (to be safe) the entire <path>images</path>
110 drobbins 1.1 directory.
111     </p>
112    
113     </body>
114     </section>
115     </chapter>
116 swift 1.15
117 drobbins 1.1 <chapter>
118 swift 1.15 <title>Guide XML</title>
119 drobbins 1.1 <section>
120     <title>Basic structure</title>
121     <body>
122    
123 swift 1.15 <p>
124     Now that you know how to transform guide XML, you're ready to start learning
125     the GuideXML syntax. We'll start with the the initial tags used in a guide
126     XML document:
127     </p>
128 drobbins 1.1
129     <pre caption="The initial part of a guide XML document">
130 zhen 1.6 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
131     &lt;guide link="relative_link_to_your_guide"&gt;
132 drobbins 1.1 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
133 swift 1.15 &lt;author title="<i>Chief Architect</i>"&gt;
134     &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt;
135 drobbins 1.1 &lt;/author&gt;
136 swift 1.15 &lt;author title="<i>Editor</i>"&gt;
137     &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt;
138 drobbins 1.1 &lt;/author&gt;
139    
140 swift 1.15 &lt;abstract&gt;
141     <i>This guide shows you how to compose web documentation using
142     our new lightweight Gentoo GuideXML syntax. This syntax is the official
143 drobbins 1.1 format for Gentoo Linux web documentation, and this document itself was created
144 swift 1.15 using GuideXML.</i>
145     &lt;/abstract&gt;
146 drobbins 1.1
147 swift 1.14 &lt;license/&gt;
148    
149 drobbins 1.1 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
150     &lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
151     </pre>
152    
153 swift 1.15 <p>
154     On the first, line, we see the requisite tag that identifies this as an XML
155 drobbins 1.1 document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
156     guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
157     Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
158 swift 1.15 guide document.
159     </p>
160 drobbins 1.1
161 swift 1.15 <p>
162     Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
163 drobbins 1.1 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
164     allows for an optional <c>title=</c> element, used to specify the author's
165     relationship to the document (author, co-author, editor, etc.). In this
166     particular example, the authors' names are enclosed in another tag -- a
167     <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
168     person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
169     more than one <c>&lt;author&gt;</c> element is required per guide document.
170     </p>
171    
172 swift 1.15 <p>
173     Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
174 drobbins 1.1 <c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
175     current version number, and the current version date (in DD MMM YYYY format)
176     respectively. This rounds out the tags that should appear at the beginning of
177     a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
178     tags, these tags shouldn't appear anywhere else except immediately inside the
179     <c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
180 swift 1.15 required) that these tags appear before the content of the document.
181     </p>
182 swift 1.14
183 swift 1.15 <p>
184     Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
185 swift 1.14 document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
186     Commons - Attribution / Share Alike</uri> license as required by the <uri
187     link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
188 swift 1.15 </p>
189 drobbins 1.1
190     </body>
191     </section>
192     <section>
193     <title>Chapters and sections</title>
194     <body>
195 swift 1.15
196     <p>
197     Once the initial tags have been specified, you're ready to start adding
198 drobbins 1.1 the structural elements of the document. Guide documents are divided into
199     chapters, and each chapter can hold one or more sections. Every chapter
200     and section has a title. Here's an example chapter with a single section,
201 neysx 1.16 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
202 drobbins 1.1 excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
203     (if minimal) guide document:
204     </p>
205    
206     <pre>
207     &lt;chapter&gt;
208     &lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
209     &lt;section&gt;
210 swift 1.15 &lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
211     &lt;body&gt;
212    
213     &lt;p&gt;
214     <i>This is the actual text content of my section.</i>
215     &lt;/p&gt;
216    
217     &lt;/body&gt;
218 drobbins 1.1 &lt;/section&gt;
219     &lt;/chapter&gt;
220     </pre>
221    
222 swift 1.15 <p>
223     Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
224 drobbins 1.1 element to the <c>&lt;chapter&gt;</c> element. Then, I created a section by
225     adding a <c>&lt;section&gt;</c> element. If you look inside the
226     <c>&lt;section&gt;</c> element, you'll see that it has two child elements -- a
227     <c>&lt;title&gt;</c> and a <c>&lt;body&gt;</c>. While the <c>&lt;title&gt;</c>
228     is nothing new, the <c>&lt;body&gt;</c> is -- it contains the actual text
229     content of this particular section. We'll look at the tags that are allowed
230 swift 1.15 inside a <c>&lt;body&gt;</c> element in a bit.
231     </p>
232 drobbins 1.1
233 swift 1.15 <note>
234     A <c>&lt;guide&gt;</c> element can contain multiple <c>&lt;chapter&gt;</c>
235     elements, and a <c>&lt;chapter&gt;</c> can contain multiple
236     <c>&lt;section&gt;</c> elements. However, a <c>&lt;section&gt;</c>
237     element can only contain one <c>&lt;body&gt;</c> element.
238     </note>
239 drobbins 1.1
240     </body>
241     </section>
242     <section>
243     <title>An example &lt;body&gt;</title>
244     <body>
245 swift 1.15
246 drobbins 1.1 <p>
247     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:
248     </p>
249 swift 1.15
250 drobbins 1.1 <pre>
251     &lt;p&gt;
252     This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
253     &lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website.
254     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.
255     &lt;/p&gt;
256    
257     &lt;pre&gt;
258     This is text output or code.
259     # &lt;i&gt;this is user input&lt;/i&gt;
260    
261     Make HTML/XML easier to read by using selective emphasis:
262     &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
263    
264     &lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt;
265     &lt;/pre&gt;
266 swift 1.15
267     &lt;note&gt;
268     This is a note.
269     &lt;/note&gt;
270    
271     &lt;warn&gt;
272     This is a warning.
273     &lt;/warn&gt;
274    
275     &lt;impo&gt;
276     This is important.
277     &lt;/impo&gt;
278 drobbins 1.1 </pre>
279 swift 1.15
280     <p>
281     Now, here's how this <c>&lt;body&gt;</c> element is rendered:
282     </p>
283 drobbins 1.1
284     <p>
285     This is a paragraph. <path>/etc/passwd</path> is a file.
286     <uri>http://www.gentoo.org</uri> is my favorite website.
287     Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
288     </p>
289    
290     <pre>
291     This is text output or code.
292     # <i>this is user input</i>
293    
294     Make HTML/XML easier to read by using selective emphasis:
295     &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
296    
297     <codenote>This is how to insert an inline note into the code block</codenote>
298     </pre>
299 swift 1.15
300     <note>
301     This is a note.
302     </note>
303    
304     <warn>
305     This is a warning.
306     </warn>
307    
308     <impo>
309     This is important.
310     </impo>
311    
312 drobbins 1.1 </body>
313     </section>
314     <section>
315     <title>The &lt;body&gt; tags</title>
316     <body>
317    
318 swift 1.15 <p>
319     We introduced a lot of new tags in the previous section -- here's what you
320 drobbins 1.1 need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
321     block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
322     <c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
323     Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
324     these are the only tags that should appear immediately inside a
325     <c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
326     stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
327     <c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
328 swift 1.12 preserves its whitespace exactly, making it well-suited for code excerpts.
329 swift 1.15 You can also name the <c>&lt;pre&gt;</c> tag:
330     </p>
331 swift 1.12
332     <pre caption = "Named &lt;pre&gt;">
333     &lt;pre caption = "Output of uptime"&gt;
334     # &lt;i&gt;uptime&lt;/i&gt;
335     16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
336     &lt;/pre&gt;
337     </pre>
338 drobbins 1.1
339     </body>
340     </section>
341     <section>
342     <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
343     <body>
344    
345 swift 1.15 <p>
346     The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
347 drobbins 1.1 be used inside any child <c>&lt;body&gt;</c> tag, except for
348 swift 1.15 <c>&lt;pre&gt;</c>.
349     </p>
350 drobbins 1.1
351 swift 1.15 <p>
352     The <c>&lt;path&gt;</c> element is used to mark text that refers to an
353     <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
354     <e>simple filename</e>. This element is generally rendered with a monospaced
355     font to offset it from the standard paragraph type.
356     </p>
357 drobbins 1.1
358 swift 1.15 <p>
359     The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
360 drobbins 1.1 input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
361     that they can type in that will perform some kind of action. For example, all
362     the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
363     element because they represent something that the user could type in that is
364     not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
365     quickly identify commands that they need to type in. Also, because
366     <c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
367     necessary to surround user input with double-quotes</e>. For example, don't
368     refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
369 swift 1.15 the use of unnecessary double-quotes makes a document more readable -- and
370     adorable!
371     </p>
372 drobbins 1.1
373 swift 1.15 <p>
374     <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
375 drobbins 1.1 I <e>really</e> should use semicolons more often. As you can see, this text is
376     offset from the regular paragraph type for emphasis. This helps to give your
377 swift 1.15 prose more <e>punch</e>!
378     </p>
379 drobbins 1.1
380     </body>
381     </section>
382     <section>
383     <title>&lt;mail&gt; and &lt;uri&gt;</title>
384     <body>
385    
386 swift 1.15 <p>
387     We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
388     some text with a particular email address, and takes the form <c>&lt;mail
389     link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
390     </p>
391 drobbins 1.1
392 swift 1.15 <p>
393     The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
394 drobbins 1.1 Internet. It has two forms -- the first can be used when you want to have the
395     actual URI displayed in the body text, such as this link to
396     <uri>http://www.gentoo.org</uri>. To create this link, I typed
397     <c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is
398     when you want to associate a URI with some other text -- for example, <uri
399 swift 1.15 link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
400     <e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the
401     Gentoo Linux website&lt;/uri&gt;</c>.
402 drobbins 1.1 </p>
403    
404     </body>
405     </section>
406     <section>
407     <title>Figures</title>
408    
409     <body>
410    
411 swift 1.15 <p>
412     Here's how to insert a figure into a document -- <c>&lt;figure
413 drobbins 1.1 link="mygfx.png" short="my picture" caption="my favorite picture of all
414     time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
415     the <c>short=</c> attribute specifies a short description (currently used for
416     the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
417     :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
418 swift 1.15 for adding images without captions, borders, etc.
419     </p>
420 drobbins 1.1
421     </body>
422     </section>
423     <section>
424     <title>Tables and lists</title>
425     <body>
426    
427 swift 1.15 <p>
428     Guide supports a simplified table syntax similar to that of HTML. To start
429 drobbins 1.1 a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
430     tag. However, for inserting actual table data, we <e>don't</e> support the
431     HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
432     header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
433 swift 1.15 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
434     -- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
435 drobbins 1.1 first row. Currently, these tags don't support any attributes, but some will
436     be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) soon.
437     </p>
438    
439 swift 1.15 <p>
440     To create ordered or unordered lists, simply use the HTML-style
441 drobbins 1.1 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
442     should only appear inside a <c>&lt;p&gt;</c>, <c>&lt;ti&gt;</c>,
443 swift 1.15 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
444     </p>
445 drobbins 1.1
446     </body>
447     </section>
448     <section>
449     <title>Intra-document references</title>
450     <body>
451    
452 swift 1.15 <p>
453     Guide makes it really easy to reference other parts of the document using
454 drobbins 1.1 hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
455     One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
456     One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
457     Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
458     Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
459 swift 1.15 link="doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
460     link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
461     link="doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be
462     adding other auto-link abilities (such as table support) soon.
463 swift 1.17 </p>
464    
465     </body>
466     </section>
467     </chapter>
468    
469     <chapter>
470     <title>Coding Style</title>
471     <section>
472     <title>Introduction</title>
473     <body>
474    
475     <p>
476     Since all Gentoo Documentation is a joint effort and several people will
477     most likely change existing documentation, a coding style is needed.
478     A coding style contains two sections. The first one is regarding
479     internal coding - how the xml-tags are placed. The second one is
480     regarding the content - how not to confuse the reader.
481     </p>
482    
483     <p>
484     Both sections are described next.
485     </p>
486    
487     </body>
488     </section>
489     <section>
490     <title>Internal Coding Style</title>
491     <body>
492    
493     <p>
494     <b>Newlines</b> must be placed immediately after <e>every</e>
495     GuideXML-tag (both opening as closing), except for:
496     <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
497     <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
498     <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
499     <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
500     <c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
501     </p>
502    
503     <p>
504     <b>Blank lines</b> must be placed immediately after <e>every</e>
505     <c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
506     <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
507     <c>&lt;author&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>,
508     <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and <c>&lt;impo&gt;</c> (opening tags
509     only).
510     </p>
511    
512     <p>
513     <b>Word-wrapping</b> must be applied at 80 characters except inside
514     <c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
515     this rule (for instance when a URL exceeds the maximum amount of characters).
516     The editor must then wrap whenever the first whitespace occurs.
517     </p>
518    
519     <p>
520     <b>Indentation</b> may not be used, except with the XML-constructs of which
521     the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
522     <c>&lt;ul&gt;</c> and <c>&lt;ol&gt;</c>. If indentation is used, it
523     <e>must</e> be two spaces for each indentation. That means <e>no</e> tabs and
524     <e>not</e> more spaces.
525     </p>
526    
527     <p>
528     In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
529     <c>&lt;li&gt;</c> constructs, indentation must be used for the content.
530     </p>
531    
532     <p>
533     An example for indentation is:
534     </p>
535    
536     <pre caption = "Indentation Example">
537     &lt;table&gt;
538     &lt;tr&gt;
539     &lt;th&gt;Foo&lt;/th&gt;
540     &lt;th&gt;Bar&lt;/th&gt;
541     &lt;/tr&gt;
542     &lt;tr&gt;
543     &lt;ti&gt;This is an example for indentation.&lt;/ti&gt;
544     &lt;ti&gt;
545     In case text cannot be shown within an 80-character wide line, you
546     must use indentation if the parent tag allows it.
547     &lt;/ti&gt;
548     &lt;/tr&gt;
549     &lt;/table&gt;
550    
551     &lt;ul&gt;
552     &lt;li&gt;First option&lt;/li&gt;
553     &lt;li&gt;Second option&lt;/li&gt;
554     &lt;/ul&gt;
555     </pre>
556    
557     <p>
558     <b>Attributes</b> may not have spaces in between the attribute, the
559     &quot;=&quot; mark, and the attribute value. As an example:
560     </p>
561    
562     <pre caption="Attributes">
563     <comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
564     <comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
565     </pre>
566    
567     </body>
568     </section>
569     <section>
570     <title>External Coding Style</title>
571     <body>
572    
573     <p>
574     Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
575     <c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
576     sentences are used. In that case, every sentence should end with a period (or
577     other reading marks).
578     </p>
579    
580     <p>
581     Every sentence, including those inside tables and listings, should start
582     with a capital letter.
583     </p>
584    
585     <pre caption="Periods and capital letters">
586     &lt;ul&gt;
587     &lt;li&gt;No period&lt;/li&gt;
588     &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
589     &lt;/ul&gt;
590     </pre>
591    
592     <p>
593     Code Listings should <e>always</e> have a <c>caption</c>.
594     </p>
595    
596     <p>
597     Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
598     possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
599     Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
600 swift 1.15 </p>
601 drobbins 1.1
602     </body>
603     </section>
604     </chapter>
605 swift 1.15
606 drobbins 1.1 <chapter>
607     <title>Resources</title>
608     <section>
609 swift 1.15 <title>Start writing</title>
610     <body>
611    
612     <p>
613     Guide has been specially designed to be "lean and mean" so that developers
614     can spend more time writing documentation and less time learning the actual XML
615     syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
616     to start writing quality Gentoo Linux documentation. If you'd like to help (or
617     have any questions about guide), please post a message to the <mail
618     link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
619     like to tackle. Have fun!
620     </p>
621    
622     </body>
623 drobbins 1.1 </section>
624     </chapter>
625     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20