/[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.71 Revision 1.72
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.71 2011/11/29 19:02:45 swift Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.72 2012/10/07 08:19:42 swift Exp $ -->
4 4
5<guide> 5<guide>
6<title>Gentoo GuideXML Guide</title> 6<title>Gentoo GuideXML Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="neysx"/> 9 <mail link="neysx"/>
10</author> 10</author>
11<author title="Author"> 11<author title="Author">
12 <mail link="drobbins@gentoo.org">Daniel Robbins</mail> 12 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13</author> 13</author>
14<author title="Author"><!-- zhen@gentoo.org --> 14<author title="Author"><!-- zhen@gentoo.org -->
15 John P. Davis 15 John P. Davis
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
18 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 18 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
23<author title="Editor"> 23<author title="Editor">
24 <mail link="nightmorph"/> 24 <mail link="nightmorph"/>
25</author> 25</author>
26 26
27<abstract> 27<abstract>
28This guide shows you how to compose web documentation using the new lightweight 28This guide shows you how to compose web documentation using the new lightweight
29Gentoo GuideXML syntax. This syntax is the official format for Gentoo 29Gentoo GuideXML syntax. This syntax is the official format for Gentoo
30documentation, and this document itself was created using GuideXML. This guide 30documentation, and this document itself was created using GuideXML. This guide
31assumes a basic working knowledge of XML and HTML. 31assumes a basic working knowledge of XML and HTML.
32</abstract> 32</abstract>
33 33
34<!-- The content of this document is licensed under the CC-BY-SA license --> 34<!-- The content of this document is licensed under the CC-BY-SA license -->
35<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 35<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
36<license/> 36<license/>
37 37
38<version>12</version> 38<version>13</version>
39<date>2011-11-29</date> 39<date>2012-10-07</date>
40 40
41<chapter> 41<chapter>
42<title>GuideXML basics</title> 42<title>GuideXML basics</title>
43<section> 43<section>
44<title>GuideXML design goals</title> 44<title>GuideXML design goals</title>
45<body> 45<body>
46 46
47<p> 47<p>
48The guideXML syntax is lightweight yet expressive, so that it is easy to 48The guideXML syntax is lightweight yet expressive, so that it is easy to
49learn yet also provides all the features we need for the creation of web 49learn yet also provides all the features we need for the creation of web
50documentation. The number of tags is kept to a minimum -- just those we need. 50documentation. The number of tags is kept to a minimum -- just those we need.
51This makes it easy to transform guide into other formats, such as DocBook 51This makes it easy to transform guide into other formats, such as DocBook
52XML/SGML or web-ready HTML. 52XML/SGML or web-ready HTML.
53</p> 53</p>
54 54
83<title>GuideXML</title> 83<title>GuideXML</title>
84<section> 84<section>
85<title>Basic structure</title> 85<title>Basic structure</title>
86<body> 86<body>
87 87
88<p> 88<p>
89Let's start learning the GuideXML syntax. We'll start with the the initial 89Let's start learning the GuideXML syntax. We'll start with the the initial
90tags used in a GuideXML document: 90tags used in a GuideXML document:
91</p> 91</p>
92 92
93<pre caption="The initial part of a guide XML document"> 93<pre caption="The initial part of a guide XML document">
94&lt;?xml version="1.0" encoding="UTF-8"?&gt; 94&lt;?xml version="1.0" encoding="UTF-8"?&gt;
95&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt; 95&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
96&lt;!-- &#36;Header&#36; --&gt; 96&lt;!-- &#36;Header&#36; --&gt;
97 97
98&lt;guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>"&gt; 98&lt;guide lang="<i>en</i>"&gt;
99&lt;title&gt;<i>Gentoo Documentation Guide</i>&lt;/title&gt; 99&lt;title&gt;<i>Gentoo Documentation Guide</i>&lt;/title&gt;
100 100
101&lt;author title="<i>Author</i>"&gt; 101&lt;author title="<i>Author</i>"&gt;
102 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt; 102 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
103&lt;/author&gt; 103&lt;/author&gt;
104 104
105&lt;abstract&gt; 105&lt;abstract&gt;
106<i>This guide shows you how to compose web documentation using 106<i>This guide shows you how to compose web documentation using
107our new lightweight Gentoo GuideXML syntax. This syntax is the official 107our new lightweight Gentoo GuideXML syntax. This syntax is the official
108format for Gentoo web documentation, and this document itself was created 108format for Gentoo web documentation, and this document itself was created
109using GuideXML.</i> 109using GuideXML.</i>
110&lt;/abstract&gt; 110&lt;/abstract&gt;
111 111
112&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 112&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
113&lt;!-- See http://creativecommons.org/licenses/by-sa/3.0 --&gt; 113&lt;!-- See http://creativecommons.org/licenses/by-sa/3.0 --&gt;
114&lt;license version="3.0"/&gt; 114&lt;license version="3.0"/&gt;
115 115
116&lt;version&gt;<i>1</i>&lt;/version&gt; 116&lt;version&gt;<i>1</i>&lt;/version&gt;
117&lt;date&gt;<i>2011-11-29</i>&lt;/date&gt; 117&lt;date&gt;<i>2011-11-29</i>&lt;/date&gt;
118</pre> 118</pre>
119 119
120<p> 120<p>
121On the first lines, we see the requisite tag that identifies this as an XML 121On the first lines, we see the requisite tag that identifies this as an XML
122document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line 122document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
123will be automatically modified by the CVS server and helps to track revisions. 123will be automatically modified by the CVS server and helps to track revisions.
124Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is 124Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
125enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 125enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
126<br/>
127The <c>link</c> attribute is optional and should preferably contain the
128absolute path to the document relatively to the document root even though the
129file name alone will work. It is only used to generate a link to a
130printer-friendly version of your document and check whether a translation is
131up-to-date. Our XSL back-engine passes the actual path to our XSL stylesheet.
132The link attribute is only used as a fall-back value in case the XML is
133processed by other means.
134<br/> 126<br/>
135The <c>lang</c> attribute should be used to specify the language code of your 127The <c>lang</c> attribute should be used to specify the language code of your
136document. It is used to format the date and insert strings like "<e>Note</e>", 128document. It is used to format the date and insert strings like "<e>Note</e>",
137"<e>Content</e>", etc. in the specified language. The default is English. 129"<e>Content</e>", etc. in the specified language. The default is English.
138</p> 130</p>
139 131
140<p> 132<p>
141Next, 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
142guide document. 134guide document.
143</p> 135</p>
144 136
145<p> 137<p>
146Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 138Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
147about the various authors of the document. Each <c>&lt;author&gt;</c> tag 139about the various authors of the document. Each <c>&lt;author&gt;</c> tag
148allows for an optional <c>title</c> element, used to specify the author's 140allows for an optional <c>title</c> element, used to specify the author's

Legend:
Removed from v.1.71  
changed lines
  Added in v.1.72

  ViewVC Help
Powered by ViewVC 1.1.20