/[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
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>
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>

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

  ViewVC Help
Powered by ViewVC 1.1.20