/[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.19 - (show annotations) (download) (as text)
Sat Oct 25 08:50:41 2003 UTC (10 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.18: +2 -2 lines
File MIME type: application/xml
ZhEN asked to have his e-mail address removed from all docs

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <guide link="/doc/en/xml-guide.xml">
5 <title>Gentoo Linux XML Guide</title>
6
7 <author title="Author">
8 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
9 </author>
10 <author title="Author"><!-- zhen@gentoo.org -->
11 John P. Davis
12 </author>
13 <author title="Editor">
14 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
15 </author>
16
17 <license/>
18 <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 </abstract>
24
25 <version>2.2</version>
26 <date>October 15, 2003</date>
27
28 <chapter>
29 <title>Guide basics</title>
30 <section>
31 <title>Guide XML design goals</title>
32 <body>
33
34 <p>
35 The guide XML syntax is lightweight yet expressive, so that it is easy to
36 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 XML/SGML or web-ready HTML.
40 </p>
41
42 <p>
43 The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
44 documents.
45 </p>
46
47 </body>
48 </section>
49 <section>
50 <title>How to transform guide XML into HTML</title>
51 <body>
52
53 <p>
54 Before we take a look at the guide syntax itself, it's helpful to know how
55 guide XML is transformed into web-ready HTML. To do this, we use a special
56 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 exactly how to transform the contents of the source guide XML document to
59 create the target HTML file. The processing tool that Gentoo Linux uses
60 is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
61 </p>
62
63 <pre caption="Installing libxslt">
64 # <i>emerge libxslt</i>
65 </pre>
66
67 <p>
68 Now that we have the way, we need the means, so to speak. In other words,
69 we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
70 that are available for download:
71 </p>
72
73 <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
100 <pre caption="Transforming gentoo-x86-install.xml">
101 # <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</i>
102 </pre>
103
104 <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 directory.
111 </p>
112
113 </body>
114 </section>
115 </chapter>
116
117 <chapter>
118 <title>Guide XML</title>
119 <section>
120 <title>Basic structure</title>
121 <body>
122
123 <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
129 <pre caption="The initial part of a guide XML document">
130 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
131 &lt;guide link="relative_link_to_your_guide"&gt;
132 &lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
133 &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 &lt;/author&gt;
136 &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 &lt;/author&gt;
139
140 &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 format for Gentoo Linux web documentation, and this document itself was created
144 using GuideXML.</i>
145 &lt;/abstract&gt;
146
147 &lt;license/&gt;
148
149 &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 <p>
154 On the first, line, we see the requisite tag that identifies this as an XML
155 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 guide document.
159 </p>
160
161 <p>
162 Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
163 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 <p>
173 Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
174 <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 required) that these tags appear before the content of the document.
181 </p>
182
183 <p>
184 Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
185 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 </p>
189
190 </body>
191 </section>
192 <section>
193 <title>Chapters and sections</title>
194 <body>
195
196 <p>
197 Once the initial tags have been specified, you're ready to start adding
198 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 consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
202 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 &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 &lt;/section&gt;
219 &lt;/chapter&gt;
220 </pre>
221
222 <p>
223 Above, I set the chapter title by adding a child <c>&lt;title&gt;</c>
224 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 inside a <c>&lt;body&gt;</c> element in a bit.
231 </p>
232
233 <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
240 </body>
241 </section>
242 <section>
243 <title>An example &lt;body&gt;</title>
244 <body>
245
246 <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
250 <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
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 </pre>
279
280 <p>
281 Now, here's how this <c>&lt;body&gt;</c> element is rendered:
282 </p>
283
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
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 </body>
313 </section>
314 <section>
315 <title>The &lt;body&gt; tags</title>
316 <body>
317
318 <p>
319 We introduced a lot of new tags in the previous section -- here's what you
320 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 preserves its whitespace exactly, making it well-suited for code excerpts.
329 You can also name the <c>&lt;pre&gt;</c> tag:
330 </p>
331
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
339 </body>
340 </section>
341 <section>
342 <title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
343 <body>
344
345 <p>
346 The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
347 be used inside any child <c>&lt;body&gt;</c> tag, except for
348 <c>&lt;pre&gt;</c>.
349 </p>
350
351 <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
358 <p>
359 The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
360 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 the use of unnecessary double-quotes makes a document more readable -- and
370 adorable!
371 </p>
372
373 <p>
374 <c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
375 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 prose more <e>punch</e>!
378 </p>
379
380 </body>
381 </section>
382 <section>
383 <title>&lt;mail&gt; and &lt;uri&gt;</title>
384 <body>
385
386 <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
392 <p>
393 The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the
394 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 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 </p>
403
404 </body>
405 </section>
406 <section>
407 <title>Figures</title>
408
409 <body>
410
411 <p>
412 Here's how to insert a figure into a document -- <c>&lt;figure
413 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 for adding images without captions, borders, etc.
419 </p>
420
421 </body>
422 </section>
423 <section>
424 <title>Tables and lists</title>
425 <body>
426
427 <p>
428 Guide supports a simplified table syntax similar to that of HTML. To start
429 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 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 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 <p>
440 To create ordered or unordered lists, simply use the HTML-style
441 <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 <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
444 </p>
445
446 </body>
447 </section>
448 <section>
449 <title>Intra-document references</title>
450 <body>
451
452 <p>
453 Guide makes it really easy to reference other parts of the document using
454 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 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 </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> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
508 <c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
509 <c>&lt;impo&gt;</c> (opening tags 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 </p>
601
602 <p>
603 When you comment something inside a <c>&lt;pre&gt;</c> construct, only use
604 <c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise,
605 use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e>
606 the subject of the comment.
607 </p>
608
609 <pre caption="Comment example">
610 <comment>(Substitute "john" with your user name)</comment>
611 # <i>id john</i>
612 </pre>
613
614 </body>
615 </section>
616 </chapter>
617
618 <chapter>
619 <title>Resources</title>
620 <section>
621 <title>Start writing</title>
622 <body>
623
624 <p>
625 Guide has been specially designed to be "lean and mean" so that developers
626 can spend more time writing documentation and less time learning the actual XML
627 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
628 to start writing quality Gentoo Linux documentation. If you'd like to help (or
629 have any questions about guide), please post a message to the <mail
630 link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
631 like to tackle. Have fun!
632 </p>
633
634 </body>
635 </section>
636 </chapter>
637 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20