/[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.17 Revision 1.18
10<author title="Author"> 10<author title="Author">
11 <mail link="zhen@gentoo.org">John P. Davis</mail> 11 <mail link="zhen@gentoo.org">John P. Davis</mail>
12</author> 12</author>
13<author title="Editor"> 13<author title="Editor">
14 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 14 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
15</author> 15</author>
16 16
17<license/> 17<license/>
18<abstract> 18<abstract>
19This guide shows you how to compose web documentation using the new lightweight 19This guide shows you how to compose web documentation using the new lightweight
20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21documentation, and this document itself was created using GuideXML. This guide 21documentation, and this document itself was created using GuideXML. This guide
22assumes a basic working knowledge of XML and HTML. 22assumes a basic working knowledge of XML and HTML.
23</abstract> 23</abstract>
24 24
25<version>2.1</version> 25<version>2.2</version>
26<date>October 14, 2003</date> 26<date>October 15, 2003</date>
27 27
28<chapter> 28<chapter>
29<title>Guide basics</title> 29<title>Guide basics</title>
30<section> 30<section>
31<title>Guide XML design goals</title> 31<title>Guide XML design goals</title>
32<body> 32<body>
33 33
34<p> 34<p>
35The guide XML syntax is lightweight yet expressive, so that it is easy to 35The guide XML syntax is lightweight yet expressive, so that it is easy to
36learn yet also provides all the features we need for the creation of web 36learn yet also provides all the features we need for the creation of web
37documentation. The number of tags is kept to a minimum -- just those we need. 37documentation. The number of tags is kept to a minimum -- just those we need.
38This makes it easy to transform guide into other formats, such as DocBook 38This makes it easy to transform guide into other formats, such as DocBook
39XML/SGML or web-ready HTML. 39XML/SGML or web-ready HTML.
40</p> 40</p>
41 41
492 492
493<p> 493<p>
494<b>Newlines</b> must be placed immediately after <e>every</e> 494<b>Newlines</b> must be placed immediately after <e>every</e>
495GuideXML-tag (both opening as closing), except for: 495GuideXML-tag (both opening as closing), except for:
496<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>, 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>, 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>, 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>, 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>. 500<c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
501</p> 501</p>
502 502
503<p> 503<p>
504<b>Blank lines</b> must be placed immediately after <e>every</e> 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> 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>, 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>, 507<c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
508<c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and <c>&lt;impo&gt;</c> (opening tags 508<c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
509only). 509<c>&lt;impo&gt;</c> (opening tags only).
510</p> 510</p>
511 511
512<p> 512<p>
513<b>Word-wrapping</b> must be applied at 80 characters except inside 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 514<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
515this rule (for instance when a URL exceeds the maximum amount of characters). 515this rule (for instance when a URL exceeds the maximum amount of characters).
516The editor must then wrap whenever the first whitespace occurs. 516The editor must then wrap whenever the first whitespace occurs.
517</p> 517</p>
518 518
519<p> 519<p>
520<b>Indentation</b> may not be used, except with the XML-constructs of which 520<b>Indentation</b> may not be used, except with the XML-constructs of which
521the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>), 521the 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 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 523<e>must</e> be two spaces for each indentation. That means <e>no</e> tabs and
524<e>not</e> more spaces. 524<e>not</e> more spaces.
587 &lt;li&gt;No period&lt;/li&gt; 587 &lt;li&gt;No period&lt;/li&gt;
588 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt; 588 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
589&lt;/ul&gt; 589&lt;/ul&gt;
590</pre> 590</pre>
591 591
592<p> 592<p>
593Code Listings should <e>always</e> have a <c>caption</c>. 593Code Listings should <e>always</e> have a <c>caption</c>.
594</p> 594</p>
595 595
596<p> 596<p>
597Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as 597Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
598possible. In other words, the <uri link="http://www.gentoo.org">Gentoo 598possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
599Website</uri> is preferred over <uri>http://www.gentoo.org</uri>. 599Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
600</p> 600</p>
601 601
602<p>
603When 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,
605use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e>
606the 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
602</body> 614</body>
603</section> 615</section>
604</chapter> 616</chapter>
605 617
606<chapter> 618<chapter>
607<title>Resources</title> 619<title>Resources</title>
608<section> 620<section>
609<title>Start writing</title> 621<title>Start writing</title>
610<body> 622<body>
611 623
612<p> 624<p>
613Guide has been specially designed to be "lean and mean" so that developers 625Guide has been specially designed to be "lean and mean" so that developers
614can spend more time writing documentation and less time learning the actual XML 626can spend more time writing documentation and less time learning the actual XML
615syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 627syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
616to start writing quality Gentoo Linux documentation. If you'd like to help (or 628to start writing quality Gentoo Linux documentation. If you'd like to help (or

Legend:
Removed from v.1.17  
changed lines
  Added in v.1.18

  ViewVC Help
Powered by ViewVC 1.1.20