/[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.19 Revision 1.20
10<author title="Author"><!-- zhen@gentoo.org --> 10<author title="Author"><!-- zhen@gentoo.org -->
11 John P. Davis 11 John P. Davis
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.2</version> 25<version>2.3</version>
26<date>October 15, 2003</date> 26<date>October 31, 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
42<p> 42<p>
43The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML 43The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
44documents. 44documents.
45</p> 45</p>
46 46
47</body> 47</body>
48</section> 48</section>
49<section> 49<section>
50<title>How to transform guide XML into HTML</title> 50<title>Further Resources</title>
51<body> 51<body>
52 52
53<p>
54Before we take a look at the guide syntax itself, it's helpful to know how
55guide XML is transformed into web-ready HTML. To do this, we use a special
56file called <path>guide.xsl</path>, along with a command-line XSLT processing
57tool (also called an "engine"). The <path>guide.xsl</path> file describes
58exactly how to transform the contents of the source guide XML document to
59create the target HTML file. The processing tool that Gentoo Linux uses
60is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
61</p> 53<p>
62 54If you are planning on contributing documentation to Gentoo, or you want to test
63<pre caption="Installing libxslt"> 55GuideXML, please read the <uri
64# <i>emerge libxslt</i> 56link="http://www.gentoo.org/proj/en/gdp/doc/en/docdev.xml">Documentation
65</pre> 57Developer Guide</uri> which contains tips and tricks for documentation
66 58development.
67<p>
68Now that we have the way, we need the means, so to speak. In other words,
69we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
70that are available for download:
71</p>
72
73<p>
74<b>The first type contains the entire up-to-date Gentoo Linux website</b>.
75Included are our XSL templates, so if you are planning to transform any
76documentation, you will need this tarball. The tarball can be found <uri
77link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
78</p>
79
80<p>
81<b>The second type contains daily snapshots our XML documentation source</b>
82in every language that we offer. Please note that it is impossible to transform
83documentation with this tarball, so please download the web tarball if you want
84to fully develop your own documentation. These tarballs are especially useful
85for translators. These tarballs can be found <uri
86link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
87</p>
88
89<p>
90After the web tarball is downloaded and extracted, go to the directory where
91the tarball was extracted, and enter the <path>htdocs</path> directory. Browse
92around and get comfortable with the layout, but note the <path>xsl</path> and
93<path>doc</path> directories. As you might have guessed, the XSL stylesheets are
94in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing
95purposes, we will be using the Gentoo Linux CD Installation Guide, located at
96<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL
97and XML file are known, we can do some transforming with <c>xsltproc</c>.
98</p>
99
100<pre caption="Transforming gentoo-x86-install.xml">
101# <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</i>
102</pre>
103
104<p>
105If all went well, you should have a web-ready version of
106<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For
107this document to display properly in a web browser, you may have to copy some
108files from <path>htdocs</path> to <path>/tmp</path>, such as
109<path>css/main.css</path> and (to be safe) the entire <path>images</path>
110directory.
111</p> 59</p>
112 60
113</body> 61</body>
114</section> 62</section>
115</chapter> 63</chapter>
116 64
117<chapter> 65<chapter>
118<title>Guide XML</title> 66<title>Guide XML</title>
119<section> 67<section>
120<title>Basic structure</title> 68<title>Basic structure</title>
121<body> 69<body>
122 70
123<p> 71<p>
124Now that you know how to transform guide XML, you're ready to start learning 72Now that you know how to transform guide XML, you're ready to start learning
125the GuideXML syntax. We'll start with the the initial tags used in a guide 73the GuideXML syntax. We'll start with the the initial tags used in a guide

Legend:
Removed from v.1.19  
changed lines
  Added in v.1.20

  ViewVC Help
Powered by ViewVC 1.1.20