/[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.52 Revision 1.53
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.52 2005/10/13 15:57:42 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.53 2005/10/13 20:33:40 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
8<author title="Author"> 8<author title="Author">
9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail> 9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10</author> 10</author>
11<author title="Author"><!-- zhen@gentoo.org --> 11<author title="Author"><!-- zhen@gentoo.org -->
12 John P. Davis 12 John P. Davis
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 15 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
20<author title="Editor"> 20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail> 21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author> 22</author>
23 23
24<abstract> 24<abstract>
25This guide shows you how to compose web documentation using the new lightweight 25This guide shows you how to compose web documentation using the new lightweight
26Gentoo GuideXML syntax. This syntax is the official format for Gentoo 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo
27documentation, and this document itself was created using GuideXML. This guide 27documentation, and this document itself was created using GuideXML. This guide
28assumes a basic working knowledge of XML and HTML. 28assumes a basic working knowledge of XML and HTML.
29</abstract> 29</abstract>
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.27</version> 35<version>2.28</version>
36<date>2005-10-11</date> 36<date>2005-10-13</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>
42<body> 42<body>
43 43
44<p> 44<p>
45The guide XML syntax is lightweight yet expressive, so that it is easy to 45The guide XML syntax is lightweight yet expressive, so that it is easy to
46learn yet also provides all the features we need for the creation of web 46learn yet also provides all the features we need for the creation of web
47documentation. The number of tags is kept to a minimum -- just those we need. 47documentation. The number of tags is kept to a minimum -- just those we need.
48This makes it easy to transform guide into other formats, such as DocBook 48This makes it easy to transform guide into other formats, such as DocBook
49XML/SGML or web-ready HTML. 49XML/SGML or web-ready HTML.
50</p> 50</p>
51 51
301<title>The &lt;body&gt; tags</title> 301<title>The &lt;body&gt; tags</title>
302<body> 302<body>
303 303
304<p> 304<p>
305We introduced a lot of new tags in the previous section -- here's what you need 305We introduced a lot of new tags in the previous section -- here's what you need
306to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block), 306to 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> 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 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 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 310<c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
311only tags that should appear immediately inside a <c>&lt;body&gt;</c> element. 311only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
312Another thing -- these tags <e>should not</e> be stacked -- in other words, 312Another thing -- these tags <e>should not</e> be stacked -- in other words,
313don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As 313don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
314you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace 314you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
315exactly, making it well-suited for code excerpts. You must name the 315exactly, making it well-suited for code excerpts. You must name the
316<c>&lt;pre&gt;</c> tag with a caption attribute: 316<c>&lt;pre&gt;</c> tag with a <c>caption</c> attribute:
317</p> 317</p>
318 318
319<pre caption="Named &lt;pre&gt;"> 319<pre caption="Named &lt;pre&gt;">
320&lt;pre caption="Output of uptime"&gt; 320&lt;pre caption="Output of uptime"&gt;
321# &lt;i&gt;uptime&lt;/i&gt; 321# &lt;i&gt;uptime&lt;/i&gt;
32216:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 32216:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
323&lt;/pre&gt; 323&lt;/pre&gt;
324</pre> 324</pre>
325 325
326</body> 326</body>
327</section> 327</section>
328<section> 328<section>
329<title>Epigraphs</title> 329<title>Epigraphs</title>
330<body> 330<body>
331 331
503<title>Lists</title> 503<title>Lists</title>
504<body> 504<body>
505 505
506<p> 506<p>
507To create ordered or unordered lists, simply use the XHTML-style 507To create ordered or unordered lists, simply use the XHTML-style
508<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only 508<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. Lists may only
509appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means 509appear inside the <c>&lt;body&gt;</c> and <c>&lt;li&gt;</c> tags which means
510that you can have lists inside lists. Don't forget that you are writing XML and 510that you can have lists inside lists. Don't forget that you are writing XML and
511that you must close all tags including list items unlike in HTML. 511that you must close all tags including list items unlike in HTML.
512</p> 512</p>
513 513
514<p> 514<p>
515Definition lists (<c>&lt;dl&gt;</c>) are also supported. Please note that 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 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 517(<c>&lt;dd&gt;</c>) accept any other block level tag such as paragraphs or
518admonitions. A definition list comprises 518admonitions. A definition list comprises:
519</p> 519</p>
520 520
521<dl> 521<dl>
522 <dt><c>&lt;dl&gt;</c></dt> 522 <dt><c>&lt;dl&gt;</c></dt>
523 <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> 523 <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
524 <dt><c>&lt;dt&gt;</c></dt> 524 <dt><c>&lt;dt&gt;</c></dt>
525 <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> 525 <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
526 <dt><c>&lt;dd&gt;</c></dt> 526 <dt><c>&lt;dd&gt;</c></dt>
527 <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> 527 <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
528</dl> 528</dl>
529 529
530<p> 530<p>
531The following list copied from <uri 531The following list copied from <uri
532link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows 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 533that a definition list can contain ordered and unordered lists. It may not
536 536
537<dl> 537<dl>
538 <dt><b>The ingredients:</b></dt> 538 <dt><b>The ingredients:</b></dt>
539 <dd> 539 <dd>
540 <ul> 540 <ul>
541 <li>100 g. flour</li> 541 <li>100 g. flour</li>
542 <li>10 g. sugar</li> 542 <li>10 g. sugar</li>
543 <li>1 cup water</li> 543 <li>1 cup water</li>
544 <li>2 eggs</li> 544 <li>2 eggs</li>
545 <li>salt, pepper</li> 545 <li>salt, pepper</li>
546 </ul> 546 </ul>
547 </dd> 547 </dd>
548 <dt><b>The procedure:</b></dt> 548 <dt><b>The procedure:</b></dt>
549 <dd> 549 <dd>
550 <ol> 550 <ol>
551 <li>Mix dry ingredients thoroughly.</li> 551 <li>Mix dry ingredients thoroughly</li>
552 <li>Pour in wet ingredients.</li> 552 <li>Pour in wet ingredients</li>
553 <li>Mix for 10 minutes.</li> 553 <li>Mix for 10 minutes</li>
554 <li>Bake for one hour at 300 degrees.</li> 554 <li>Bake for one hour at 300 degrees</li>
555 </ol> 555 </ol>
556 </dd> 556 </dd>
557 <dt><b>Notes:</b></dt> 557 <dt><b>Notes:</b></dt>
558 <dd>The recipe may be improved by adding raisins.</dd> 558 <dd>The recipe may be improved by adding raisins</dd>
559</dl> 559</dl>
560 560
561</body> 561</body>
562</section> 562</section>
563<section> 563<section>
564<title>Intra-document references</title> 564<title>Intra-document references</title>
565<body> 565<body>
566 566
567<p> 567<p>
568Guide makes it really easy to reference other parts of the document using 568Guide makes it really easy to reference other parts of the document using
569hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter 569hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
570One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter 570One</uri> by typing <c>&lt;uri link="#doc_chap1"&gt;Chapter
571One&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
572Chapter 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
573Chapter 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
684<c>&lt;impo&gt;</c> (opening tags only). 684<c>&lt;impo&gt;</c> (opening tags only).
685</p> 685</p>
686 686
687<p> 687<p>
688<b>Word-wrapping</b> must be applied at 80 characters except inside 688<b>Word-wrapping</b> must be applied at 80 characters except inside
689<c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other 689<c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
690choice (for instance when a URL exceeds the maximum amount of characters). The 690choice (for instance when a URL exceeds the maximum amount of characters). The
691editor must then wrap whenever the first whitespace occurs. You should try to 691editor must then wrap whenever the first whitespace occurs. You should try to
692keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80 692keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
693columns to help console users. 693columns to help console users.
694</p> 694</p>
695 695
696<p> 696<p>
697<b>Indentation</b> may not be used, except with the XML-constructs of which the 697<b>Indentation</b> may not be used, except with the XML-constructs of which the
698parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>), 698parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
699<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation 699<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>, <c>&lt;dl&gt;</c>, and
700is used, it <e>must</e> be two spaces for each indentation. That means <e>no 700<c>&lt;author&gt;</c>. If indentation is used, it <e>must</e> be two spaces for
701tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML 701each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
702documents. 702Besides, tabs are not allowed in GuideXML documents.
703</p>
704
705<p> 703</p>
704
705<p>
706In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or 706In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>,
707<c>&lt;li&gt;</c> constructs, indentation must be used for the content. 707<c>&lt;li&gt;</c> or <c>&lt;dd&gt;</c>constructs, indentation must be used for
708the content.
708</p> 709</p>
709 710
710<p> 711<p>
711An example for indentation is: 712An example for indentation is:
712</p> 713</p>
713 714
714<pre caption="Indentation Example"> 715<pre caption="Indentation Example">
715&lt;table&gt; 716&lt;table&gt;
716&lt;tr&gt; 717&lt;tr&gt;
717 &lt;th&gt;Foo&lt;/th&gt; 718 &lt;th&gt;Foo&lt;/th&gt;
718 &lt;th&gt;Bar&lt;/th&gt; 719 &lt;th&gt;Bar&lt;/th&gt;
719&lt;/tr&gt; 720&lt;/tr&gt;
720&lt;tr&gt; 721&lt;tr&gt;
721 &lt;ti&gt;This is an example for indentation&lt;/ti&gt; 722 &lt;ti&gt;This is an example for indentation&lt;/ti&gt;
722 &lt;ti&gt; 723 &lt;ti&gt;
723 In case text cannot be shown within an 80-character wide line, you 724 In case text cannot be shown within an 80-character wide line, you
724 must use indentation if the parent tag allows it 725 must use indentation if the parent tag allows it
725 &lt;/ti&gt; 726 &lt;/ti&gt;
726&lt;/tr&gt; 727&lt;/tr&gt;
727&lt;/table&gt; 728&lt;/table&gt;
728 729
729&lt;ul&gt; 730&lt;ul&gt;
730 &lt;li&gt;First option&lt;/li&gt; 731 &lt;li&gt;First option&lt;/li&gt;
731 &lt;li&gt;Second option&lt;/li&gt; 732 &lt;li&gt;Second option&lt;/li&gt;
732&lt;/ul&gt; 733&lt;/ul&gt;
733</pre> 734</pre>
734 735
735<p> 736<p>
736<b>Attributes</b> may not have spaces in between the attribute, the 737<b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
737&quot;=&quot; mark, and the attribute value. As an example: 738and the attribute value. As an example:
738</p> 739</p>
739 740
740<pre caption="Attributes"> 741<pre caption="Attributes">
741<comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt; 742<comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
742<comment>Correct:</comment> &lt;pre caption="Attributes"&gt; 743<comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
743</pre> 744</pre>
744 745
745</body> 746</body>
746</section> 747</section>
747<section> 748<section>
748<title>External Coding Style</title> 749<title>External Coding Style</title>
749<body> 750<body>
750 751
751<p> 752<p>
752Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and 753Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c>,
753<c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple 754<c>&lt;ol&gt;</c>) and <c>&lt;dl&gt;</c>, periods (".") should not be used
754sentences are used. In that case, every sentence should end with a period (or 755unless multiple sentences are used. In that case, every sentence should end
755other reading marks). 756with a period (or other reading marks).
756</p> 757</p>
757 758
758<p> 759<p>
759Every sentence, including those inside tables and listings, should start 760Every sentence, including those inside tables and listings, should start
760with a capital letter. 761with a capital letter.
761</p> 762</p>
762 763
763<pre caption="Periods and capital letters"> 764<pre caption="Periods and capital letters">
764&lt;ul&gt; 765&lt;ul&gt;
765 &lt;li&gt;No period&lt;/li&gt; 766 &lt;li&gt;No period&lt;/li&gt;
766 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt; 767 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
767&lt;/ul&gt; 768&lt;/ul&gt;
768</pre> 769</pre>
769 770
770<p> 771<p>

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

  ViewVC Help
Powered by ViewVC 1.1.20