/[gentoo]/xml/htdocs/doc/en/xml-guide.xml
Gentoo

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.51 Revision 1.52
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.52 2005/10/13 15:57:42 neysx Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/xml-guide.xml"> 5<guide link="/doc/en/xml-guide.xml">
6<title>Gentoo XML Guide</title> 6<title>Gentoo XML Guide</title>
7 7
30 30
31<!-- The content of this document is licensed under the CC-BY-SA license --> 31<!-- The content of this document is licensed under the CC-BY-SA license -->
32<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 32<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33<license/> 33<license/>
34 34
35<version>2.26</version> 35<version>2.27</version>
36<date>2005-10-09</date> 36<date>2005-10-11</date>
37 37
38<chapter> 38<chapter>
39<title>Guide basics</title> 39<title>Guide basics</title>
40<section> 40<section>
41<title>Guide XML design goals</title> 41<title>Guide XML design goals</title>
60<title>Further Resources</title> 60<title>Further Resources</title>
61<body> 61<body>
62 62
63<p> 63<p>
64If you are planning on contributing documentation to Gentoo, or you want to 64If you are planning on contributing documentation to Gentoo, or you want to
65test GuideXML, please read the <uri 65test GuideXML, please read our <uri
66link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which 66link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
67contains tips and tricks for documentation development. 67which contains tips and tricks for documentation development.
68</p>
69
70<p>
71You may want to look at the <uri link="?passthru=1">XML source</uri> of this
72document while you read it.
68</p> 73</p>
69 74
70</body> 75</body>
71</section> 76</section>
72</chapter> 77</chapter>
133</p> 138</p>
134 139
135<p> 140<p>
136Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 141Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
137about the various authors of the document. Each <c>&lt;author&gt;</c> tag 142about the various authors of the document. Each <c>&lt;author&gt;</c> tag
138allows for an optional <c>title=</c> element, used to specify the author's 143allows for an optional <c>title</c> element, used to specify the author's
139relationship to the document (author, co-author, editor, etc.). In this 144relationship to the document (author, co-author, editor, etc.). In this
140particular example, the authors' names are enclosed in another tag -- a 145particular example, the authors' names are enclosed in another tag -- a
141<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular 146<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
142person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no 147person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
143more than one <c>&lt;author&gt;</c> element is required per guide document. 148more than one <c>&lt;author&gt;</c> element is required per guide document.
295<section> 300<section>
296<title>The &lt;body&gt; tags</title> 301<title>The &lt;body&gt; tags</title>
297<body> 302<body>
298 303
299<p> 304<p>
300We introduced a lot of new tags in the previous section -- here's what you 305We introduced a lot of new tags in the previous section -- here's what you need
301need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code 306to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block),
302block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and 307<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and <c>&lt;impo&gt;</c>
303<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text. 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
304Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit), 310<c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
305these are the only tags that should appear immediately inside a 311only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
306<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be 312Another thing -- these tags <e>should not</e> be stacked -- in other words,
307stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a 313don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
308<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 314you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
309preserves its whitespace exactly, making it well-suited for code excerpts. 315exactly, making it well-suited for code excerpts. You must name the
310You must name the <c>&lt;pre&gt;</c> tag with a caption attribute: 316<c>&lt;pre&gt;</c> tag with a caption attribute:
311</p> 317</p>
312 318
313<pre caption="Named &lt;pre&gt;"> 319<pre caption="Named &lt;pre&gt;">
314&lt;pre caption="Output of uptime"&gt; 320&lt;pre caption="Output of uptime"&gt;
315# &lt;i&gt;uptime&lt;/i&gt; 321# &lt;i&gt;uptime&lt;/i&gt;
318</pre> 324</pre>
319 325
320</body> 326</body>
321</section> 327</section>
322<section> 328<section>
323<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt; and &lt;e&gt;</title> 329<title>Epigraphs</title>
330<body>
331
332<p by="Anonymous student">
333Delegates from the original 13 states formed the Contented Congress. Thomas
334Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
335of Independence. Franklin discovered electricity by rubbing two cats backwards
336and declared, "A horse divided against itself cannot stand." Franklin died in
3371790 and is still dead.
338</p>
339
340<p>
341Epigraphs are sometimes used at the beginning of chapters to illustrate what is
342to follow. It is simply a paragraph with a <c>by</c> attribute that contains
343the signature.
344</p>
345
346<pre caption="Short epigraph">
347&lt;p by="Anonymous student"&gt;
348Delegates from the original 13 states formed the...
349&lt;/p&gt;
350</pre>
351
324<body> 352</body>
353</section>
354<section>
355<title>
356 &lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
357</title>
358<body>
325 359
326<p> 360<p>
327The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c> and <c>&lt;e&gt;</c> elements can 361The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
328be used inside any child <c>&lt;body&gt;</c> tag, except for
329<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside 362<c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
330<c>&lt;pre&gt;</c>. 363<c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c>
364element can only be used inside <c>&lt;pre&gt;</c>.
331</p> 365</p>
332 366
333<p> 367<p>
334The <c>&lt;path&gt;</c> element is used to mark text that refers to an 368The <c>&lt;path&gt;</c> element is used to mark text that refers to an
335<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a 369<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
365<p> 399<p>
366<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 400<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
367I <e>really</e> should use semicolons more often. As you can see, this text is 401I <e>really</e> should use semicolons more often. As you can see, this text is
368offset from the regular paragraph type for emphasis. This helps to give your 402offset from the regular paragraph type for emphasis. This helps to give your
369prose more <e>punch</e>! 403prose more <e>punch</e>!
404</p>
405
406<p>
407The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
408<sub>subscript</sub> and <sup>superscript</sup>.
370</p> 409</p>
371 410
372</body> 411</body>
373</section> 412</section>
374<section> 413<section>
407<body> 446<body>
408 447
409<p> 448<p>
410Here's how to insert a figure into a document -- <c>&lt;figure 449Here's how to insert a figure into a document -- <c>&lt;figure
411link="mygfx.png" short="my picture" caption="my favorite picture of all 450link="mygfx.png" short="my picture" caption="my favorite picture of all
412time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image, 451time"/&gt;</c>. The <c>link</c> attribute points to the actual graphic image,
413the <c>short=</c> attribute specifies a short description (currently used for 452the <c>short</c> attribute specifies a short description (currently used for
414the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult 453the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
415:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag 454:) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
416for adding images without captions, borders, etc. 455for adding images without captions, borders, etc.
417</p> 456</p>
418 457
419</body> 458</body>
420</section> 459</section>
421<section> 460<section>
422<title>Tables and lists</title> 461<title>Tables</title>
423<body> 462<body>
424 463
425<p> 464<p>
426Guide supports a simplified table syntax similar to that of HTML. To start a 465Guide supports a simplified table syntax similar to that of HTML. To start a
427table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c> 466table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
428tag. However, for inserting actual table data, we <e>don't</e> support the 467tag. However, for inserting actual table data, we <e>don't</e> support the
429HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a 468HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
430header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational 469header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
431block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> 470block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
432-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the 471-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
433first row. 472first row.
434</p> 473</p>
435 474
436<p> 475<p>
476Besides, the table header tag (<c>&lt;th&gt;</c>) accepts the <c>colspan</c>
477and <c>rowspan</c> attributes to span titles across rows, columns or both as
478shown below:
479</p>
480
481<table>
482 <tr>
483 <th colspan="4">This title spans 4 columns</th>
484 </tr>
485 <tr>
486 <th rowspan="3">This title spans 3 rows</th>
487 <ti>Item A1</ti>
488 <ti>Item A2</ti>
489 <ti>Item A3</ti>
490 </tr>
491 <tr>
492 <ti>Item B1</ti>
493 <th colspan="2" rowspan="2">Blocky 2x2 title</th>
494 </tr>
495 <tr>
496 <ti>Item C1</ti>
497 </tr>
498</table>
499
500</body>
501</section>
502<section>
503<title>Lists</title>
504<body>
505
506<p>
437To create ordered or unordered lists, simply use the XHTML-style 507To create ordered or unordered lists, simply use the XHTML-style
438<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags 508<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
439should only appear inside a <c>&lt;body&gt;</c>, <c>&lt;ul&gt;</c> or 509appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
440<c>&lt;ol&gt;</c> tag. You need to close the tags as well (which is a general 510that you can have lists inside lists. Don't forget that you are writing XML and
441XML requirement). 511that you must close all tags including list items unlike in HTML.
512</p>
513
442</p> 514<p>
515Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that
516neither the definition term tag (<c>&lt;dt&gt;</c>) nor the definition data tag
517(<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
518admonitions. A definition list comprises
519</p>
520
521<dl>
522 <dt><c>&lt;dl&gt;</c></dt>
523 <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
524 <dt><c>&lt;dt&gt;</c></dt>
525 <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
526 <dt><c>&lt;dd&gt;</c></dt>
527 <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
528</dl>
529
530<p>
531The following list copied from <uri
532link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
533that a definition list can contain ordered and unordered lists. It may not
534contain another definition list though.
535</p>
536
537<dl>
538 <dt><b>The ingredients:</b></dt>
539 <dd>
540 <ul>
541 <li>100 g. flour</li>
542 <li>10 g. sugar</li>
543 <li>1 cup water</li>
544 <li>2 eggs</li>
545 <li>salt, pepper</li>
546 </ul>
547 </dd>
548 <dt><b>The procedure:</b></dt>
549 <dd>
550 <ol>
551 <li>Mix dry ingredients thoroughly.</li>
552 <li>Pour in wet ingredients.</li>
553 <li>Mix for 10 minutes.</li>
554 <li>Bake for one hour at 300 degrees.</li>
555 </ol>
556 </dd>
557 <dt><b>Notes:</b></dt>
558 <dd>The recipe may be improved by adding raisins.</dd>
559</dl>
443 560
444</body> 561</body>
445</section> 562</section>
446<section> 563<section>
447<title>Intra-document references</title> 564<title>Intra-document references</title>
454One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of 571One&lt;/uri&gt;</c>. To point to <uri link="#doc_chap1_sect2">section two of
455Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of 572Chapter One</uri>, type <c>&lt;uri link="#doc_chap1_sect2"&gt;section two of
456Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri 573Chapter One&lt;/uri&gt;</c>. To refer to figure 3 in chapter 1, type <c>&lt;uri
457link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri 574link="#doc_chap1_fig3"&gt;figure 1.3&lt;/uri&gt;</c>. Or, to refer to <uri
458link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri 575link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c>&lt;uri
459link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>. We'll be 576link="#doc_chap2_pre2"&gt;code listing 2.2&lt;/uri&gt;</c>.
460adding other auto-link abilities (such as table support) soon.
461</p> 577</p>
462 578
463<p> 579<p>
464However, some guides change often and using such "counting" can lead to broken 580However, some guides change often and using such "counting" can lead to broken
465links. In order to cope with this, you can define a name for a 581links. In order to cope with this, you can define a name for a

Legend:
Removed from v.1.51  
changed lines
  Added in v.1.52

  ViewVC Help
Powered by ViewVC 1.1.20