/[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.13 Revision 1.14
3 3
4<guide link="/doc/en/xml-guide.xml"> 4<guide link="/doc/en/xml-guide.xml">
5<title>Gentoo Linux XML Guide</title> 5<title>Gentoo Linux XML Guide</title>
6<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> 6<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
7<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author> 7<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
8<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author> 8<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>
9 9
10<license/> 10<license/>
11 11
12<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide 12<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide
13XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document 13XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document
14itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. 14itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML.
15</abstract> 15</abstract>
16 16
17<version>2.0</version> 17<version>2.0</version>
18<date>12 May 2003</date> 18<date>4th of August 2003</date>
19 19
20<chapter> 20<chapter>
21<title>Guide basics</title> 21<title>Guide basics</title>
22 22
23<section> 23<section>
24<title>Guide XML design goals</title> 24<title>Guide XML design goals</title>
25<body> 25<body>
26 26
27<p> The guide XML syntax is lightweight yet expressive, so that it is easy to 27<p> The guide XML syntax is lightweight yet expressive, so that it is easy to
28learn yet also provides all the features we need for the creation of web 28learn yet also provides all the features we need for the creation of web
29documentation. The number of tags is kept to a minimum -- just those we need. 29documentation. The number of tags is kept to a minimum -- just those we need.
30This makes it easy to transform guide into other formats, such as DocBook 30This makes it easy to transform guide into other formats, such as DocBook
31XML/SGML or web-ready HTML. </p> 31XML/SGML or web-ready HTML. </p>
32 32
33<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML 33<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
109&lt;?xml version='1.0' encoding="UTF-8"?&gt; 109&lt;?xml version='1.0' encoding="UTF-8"?&gt;
110&lt;guide link="relative_link_to_your_guide"&gt; 110&lt;guide link="relative_link_to_your_guide"&gt;
111&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 111&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
112&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt; 112&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt;
113 <i>Daniel Robbins</i>&lt;/mail&gt; 113 <i>Daniel Robbins</i>&lt;/mail&gt;
114&lt;/author&gt; 114&lt;/author&gt;
115&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt; 115&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
116 <i>Thomas Flavel</i>&lt;/mail&gt; 116 <i>Thomas Flavel</i>&lt;/mail&gt;
117&lt;/author&gt; 117&lt;/author&gt;
118 118
119&lt;abstract&gt;<i>This guide shows you how to compose web documentation using 119&lt;abstract&gt;<i>This guide shows you how to compose web documentation using
120our new lightweight Gentoo guide XML syntax. This syntax is the official 120our new lightweight Gentoo guide XML syntax. This syntax is the official
121format for Gentoo Linux web documentation, and this document itself was created 121format for Gentoo Linux web documentation, and this document itself was created
122using guide XML.</i> &lt;/abstract&gt; 122using guide XML.</i> &lt;/abstract&gt;
123 123
124&lt;license/&gt;
125
124&lt;version&gt;<i>1.0</i>&lt;/version&gt; 126&lt;version&gt;<i>1.0</i>&lt;/version&gt;
125&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt; 127&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
126</pre> 128</pre>
127 129
128<p>On the first, line, we see the requisite tag that identifies this as an XML 130<p>On the first, line, we see the requisite tag that identifies this as an XML
129document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire 131document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
130guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 132guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
131Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 133Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
132guide document. </p> 134guide document. </p>
133 135
134<p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 136<p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
135about the various authors of the document. Each <c>&lt;author&gt;</c> tag 137about the various authors of the document. Each <c>&lt;author&gt;</c> tag
136allows for an optional <c>title=</c> element, used to specify the author's 138allows for an optional <c>title=</c> element, used to specify the author's
137relationship to the document (author, co-author, editor, etc.). In this 139relationship to the document (author, co-author, editor, etc.). In this
138particular example, the authors' names are enclosed in another tag -- a 140particular example, the authors' names are enclosed in another tag -- a
139<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular 141<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
140person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no 142person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
141more than one <c>&lt;author&gt;</c> element is required per guide document. 143more than one <c>&lt;author&gt;</c> element is required per guide document.
142</p> 144</p>
143 145
144<p>Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and 146<p>Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
145<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the 147<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
146current version number, and the current version date (in DD MMM YYYY format) 148current version number, and the current version date (in DD MMM YYYY format)
147respectively. This rounds out the tags that should appear at the beginning of 149respectively. This rounds out the tags that should appear at the beginning of
148a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> 150a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
149tags, these tags shouldn't appear anywhere else except immediately inside the 151tags, these tags shouldn't appear anywhere else except immediately inside the
150<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 152<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
151required) that these tags appear before the content of the document. </p> 153required) that these tags appear before the content of the document. </p>
154
155<p>Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
156document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
157Commons - Attribution / Share Alike</uri> license as required by the <uri
158link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
159 </p>
152 160
153</body> 161</body>
154</section> 162</section>
155 163
156<section> 164<section>
157<title>Chapters and sections</title> 165<title>Chapters and sections</title>
158<body> 166<body>
159<p>Once the initial tags have been specified, you're ready to start adding 167<p>Once the initial tags have been specified, you're ready to start adding
160the structural elements of the document. Guide documents are divided into 168the structural elements of the document. Guide documents are divided into
161chapters, and each chapter can hold one or more sections. Every chapter 169chapters, and each chapter can hold one or more sections. Every chapter
162and section has a title. Here's an example chapter with a single section, 170and section has a title. Here's an example chapter with a single section,
163consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous 171consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous
164excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid 172excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid
165(if minimal) guide document: 173(if minimal) guide document:
166</p> 174</p>

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.14

  ViewVC Help
Powered by ViewVC 1.1.20