/[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.48 Revision 1.49
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.48 2005/08/11 11:01:06 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.49 2005/08/23 09:18:12 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 Linux XML Guide</title> 6<title>Gentoo Linux 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 Linux 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
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.24</version> 35<version>2.25</version>
36<date>2005-08-11</date> 36<date>2005-08-23</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
… …
77<title>Basic structure</title> 77<title>Basic structure</title>
78<body> 78<body>
79 79
80<p> 80<p>
81Let's start learning the GuideXML syntax. We'll start with the the initial 81Let's start learning the GuideXML syntax. We'll start with the the initial
82tags used in a GuideXML document: 82tags used in a GuideXML document:
83</p> 83</p>
84 84
85<pre caption="The initial part of a guide XML document"> 85<pre caption="The initial part of a guide XML document">
86&lt;?xml version="1.0" encoding="UTF-8"?&gt; 86&lt;?xml version="1.0" encoding="UTF-8"?&gt;
87&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt; 87&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
88&lt;!-- &#36;Header&#36; --&gt; 88&lt;!-- &#36;Header&#36; --&gt;
89 89
90&lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt; 90&lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt;
91&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 91&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
92
92&lt;author title="<i>Author</i>"&gt; 93&lt;author title="<i>Author</i>"&gt;
93 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt; 94 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
94&lt;/author&gt; 95&lt;/author&gt;
95 96
96&lt;abstract&gt; 97&lt;abstract&gt;
97<i>This guide shows you how to compose web documentation using 98<i>This guide shows you how to compose web documentation using
98our new lightweight Gentoo GuideXML syntax. This syntax is the official 99our new lightweight Gentoo GuideXML syntax. This syntax is the official
99format for Gentoo Linux web documentation, and this document itself was created 100format for Gentoo Linux web documentation, and this document itself was created
100using GuideXML.</i> 101using GuideXML.</i>
101&lt;/abstract&gt; 102&lt;/abstract&gt;
102 103
103&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 104&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
104&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt; 105&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
105&lt;license/&gt; 106&lt;license/&gt;
106 107
… …
146current version number, and the current version date (in YYYY-MM-DD format) 147current version number, and the current version date (in YYYY-MM-DD format)
147respectively. Dates that are invalid or not in the YYYY-MM-DD format will 148respectively. Dates that are invalid or not in the YYYY-MM-DD format will
148appear verbatim in the rendered document. 149appear verbatim in the rendered document.
149</p> 150</p>
150 151
151<p> 152<p>
152This rounds out the tags that should appear at the beginning of a guide 153This rounds out the tags that should appear at the beginning of a guide
153document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these 154document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these
154tags shouldn't appear anywhere else except immediately inside the 155tags shouldn't appear anywhere else except immediately inside the
155<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 156<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
156required) that these tags appear before the content of the document. 157required) that these tags appear before the content of the document.
157</p> 158</p>
158 159
159<p> 160<p>
160Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document 161Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the document
161under the <uri link="http://creativecommons.org/licenses/by-sa/2.0/">Creative 162under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
162Commons - Attribution / Share Alike</uri> license as required by the <uri 163Commons - Attribution / Share Alike</uri> license as required by the <uri
163link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. 164link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
164</p> 165</p>
165 166
166</body> 167</body>
167</section> 168</section>
168<section> 169<section>
169<title>Chapters and sections</title> 170<title>Chapters and sections</title>
170<body> 171<body>
171 172
172<p> 173<p>
173Once the initial tags have been specified, you're ready to start adding the 174Once the initial tags have been specified, you're ready to start adding the
174structural elements of the document. Guide documents are divided into 175structural elements of the document. Guide documents are divided into
175chapters, and each chapter can hold one or more sections. Every chapter and 176chapters, and each chapter can hold one or more sections. Every chapter and
176section has a title. Here's an example chapter with a single section, 177section has a title. Here's an example chapter with a single section,
… …
651&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt; 652&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
652&lt;!-- &#36;Header&#36; --&gt; 653&lt;!-- &#36;Header&#36; --&gt;
653 654
654&lt;<i>book</i> link="example.xml"&gt; 655&lt;<i>book</i> link="example.xml"&gt;
655&lt;title&gt;Example Book Usage&lt;/title&gt; 656&lt;title&gt;Example Book Usage&lt;/title&gt;
656 657
657&lt;author...&gt; 658&lt;author...&gt;
658 ... 659 ...
659&lt;/author&gt; 660&lt;/author&gt;
660 661
661&lt;abstract&gt; 662&lt;abstract&gt;
662 ... 663 ...
663&lt;/abstract&gt; 664&lt;/abstract&gt;
664 665
665&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 666&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
666&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 667&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
667&lt;license/&gt; 668&lt;license/&gt;
668 669
669&lt;version&gt;...&lt;/version&gt; 670&lt;version&gt;...&lt;/version&gt;
670&lt;date&gt;...&lt;/date&gt; 671&lt;date&gt;...&lt;/date&gt;
671</pre> 672</pre>
672 673
673<p> 674<p>
674So far no real differences (except for the <c>&lt;book&gt;</c> instead of 675So far no real differences (except for the <c>&lt;book&gt;</c> instead of
675<c>&lt;guide&gt;</c> tag). Instead of starting with the individual 676<c>&lt;guide&gt;</c> tag). Instead of starting with the individual
676<c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the 677<c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the
677equivalent of a separate part in a book: 678equivalent of a separate part in a book:
678</p> 679</p>
679 680
680<pre caption="Defining a part"> 681<pre caption="Defining a part">
681&lt;part&gt; 682&lt;part&gt;
… …
716</section> 717</section>
717<section> 718<section>
718<title>Designing the Individual Chapters</title> 719<title>Designing the Individual Chapters</title>
719<body> 720<body>
720 721
721<p> 722<p>
722The content of an individual chapter is structured as follows: 723The content of an individual chapter is structured as follows:
723</p> 724</p>
724 725
725<pre caption="Chapter Syntax"> 726<pre caption="Chapter Syntax">
726&lt;?xml version='1.0' encoding='UTF-8'?&gt; 727&lt;?xml version='1.0' encoding='UTF-8'?&gt;
727&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt; 728&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
728&lt;!-- &#36;Header&#36; --&gt; 729&lt;!-- &#36;Header&#36; --&gt;
729 730
730&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 731&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
731&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 732&lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
732 733
733&lt;sections&gt; 734&lt;sections&gt;
734 735
735&lt;version&gt;...&lt;/version&gt; 736&lt;version&gt;...&lt;/version&gt;
736&lt;date&gt;...&lt;/date&gt; 737&lt;date&gt;...&lt;/date&gt;
737 738
738<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment> 739<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
739 740
740&lt;/sections&gt; 741&lt;/sections&gt;
741</pre> 742</pre>
742 743
743<p> 744<p>
744Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of 745Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
745<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent 746<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
746of <c>&lt;section&gt;</c> in a Guide). 747of <c>&lt;section&gt;</c> in a Guide).
Legend:
Removed from v.1.48  
changed lines
  Added in v.1.49
  ViewVC Help
Powered by ViewVC 1.1.20