/[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
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>
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;
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>
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>
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>
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;
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.

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

  ViewVC Help
Powered by ViewVC 1.1.20