/[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.8 Revision 1.9
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 3
4<guide link="/doc/en/xml-guide.xml"> 4<guide link="/doc/en/xml-guide.xml">
5<title>Gentoo Linux Documentation 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="Editor"><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 8
9<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide 9<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide
10XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document 10XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document
11itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. 11itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML.
12</abstract> 12</abstract>
13 13
14<version>1.2</version> 14<version>2.0</version>
15<date>16 January 2002</date> 15<date>06 March 2003</date>
16 16
17<chapter> 17<chapter>
18<title>Guide basics</title> 18<title>Guide basics</title>
19 19
20<section> 20<section>
40<p> Before we take a look at the guide syntax itself, it's helpful to know how 40<p> Before we take a look at the guide syntax itself, it's helpful to know how
41guide XML is transformed into web-ready HTML. To do this, we use a special 41guide XML is transformed into web-ready HTML. To do this, we use a special
42file called <path>guide.xsl</path>, along with a command-line XSLT processing 42file called <path>guide.xsl</path>, along with a command-line XSLT processing
43tool (also called an "engine"). The <path>guide.xsl</path> file describes 43tool (also called an "engine"). The <path>guide.xsl</path> file describes
44exactly how to transform the contents of the source guide XML document to 44exactly how to transform the contents of the source guide XML document to
45create the target HTML file. Two popular XSLT processors are <c>sabcmd</c> 45create the target HTML file. The processing tool that Gentoo Linux uses
46(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c> 46is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. </p>
47(found in the <path>dev-libs/libxslt</path> package). From experience, we've
48found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
49processor. </p>
50 47
51 48
52<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're 49<pre caption="Installing libxslt">
53ready to convert guide XML into web-ready HTML. In order to do this though, 50# <c>emerge libxslt</c>
54it is necessary to get the latest snapshot of our website tree.
55</p> 51</pre>
56 52
57<p>The gzipped tarball for the website can be found 53<p>Now that we have the way, we need the means, so to speak. In other words,
54we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
55that are available for download: </p>
56
57<p><b>The first type contains the entire up-to-date Gentoo Linux website</b>.
58Included are our XSL templates, so if you are planning to transform any documentation,
59you will need this tarball. The tarball can be found
58<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>. 60<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.</p>
59</p>
60 61
61<note>You can now download the full set of Gentoo Linux documentation for your language 62<p><b>The second type contains daily snapshots our XML documentation source</b> in
62of choice without having to download the full web tree. Please navigate to 63every language that we offer. Please note that it is impossible to transform
63<uri>http://www.gentoo.org/dyn/doc-snapshots</uri> to find the tarballs. 64documentation with this tarball, so please download the web tarball if you want to fully
64</note> 65develop your own documentation. These tarballs are especially useful for translators.
65 66These tarballs can be found <uri link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
66<p>Now, extract the tarball. Inside it, you'll find a <path>htdocs</path>
67directory. Now, find <path>htdocs/doc/&lt;your lang&gt;/gentoo-x86-install.xml</path>
68(The new user installation guide). This will be our source XML guide document.
69The easiest way to perform the transformation is to change directories to the location of the
70<path>guide.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
71</p> 67</p>
68
69<p>After the web tarball is downloaded and extracted, go
70to the directory where the tarball was extracted, and enter the
71<path>htdocs</path> directory. Browse around and get comfortable with the
72layout, but note the <path>xsl</path> and <path>doc</path> directories.
73As you might have guessed, the XSL stylesheets are in <path>xsl</path>,
74and our documentation is in <path>doc</path>. For testing purposes, we
75will be using the Gentoo Linux CD Installation Guide, located at
76<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations
77of the XSL and XML file are known, we can do some transforming with
78<c>xsltproc</c>. </p>
72 79
73<pre caption="Transforming gentoo-x86-install.xml"> 80<pre caption="Transforming gentoo-x86-install.xml">
74# <c>cd gentoo-web/xsl</c>
75# <c>xsltproc guide.xsl ../doc/&lt;your lang&gt;/gentoo-x86-install.xml &gt; /tmp/install.html</c> 81# <c>xsltproc xsl/guide.xsl ../doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
76</pre> 82</pre>
77 83
78<p> If all went well, you should have a web-ready version of 84<p> If all went well, you should have a web-ready version of
79<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document 85<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document
80to display properly in a web browser, you may have to copy some files from 86to display properly in a web browser, you may have to copy some files from
81<path>htdocs</path> to <path>/tmp</path>, such 87<path>htdocs</path> to <path>/tmp</path>, such
82as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path> 88as <path>css/main.css</path> and (to be safe) the entire <path>images</path>
83directory. 89directory.
84</p> 90</p>
85 91
86</body> 92</body>
87</section> 93</section>
113using guide XML.</i> &lt;/abstract&gt; 119using guide XML.</i> &lt;/abstract&gt;
114 120
115&lt;version&gt;<i>1.0</i>&lt;/version&gt; 121&lt;version&gt;<i>1.0</i>&lt;/version&gt;
116&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt; 122&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
117</pre> 123</pre>
118
119<impo>If you are going to be submitting documents, it is necessary to read the
120<uri link="http://www.gentoo.org/doc/en/doc-developer-guide.xml">Gentoo Documentation Developer's Policy</uri>.
121</impo>
122 124
123<p>On the first, line, we see the requisite tag that identifies this as an XML 125<p>On the first, line, we see the requisite tag that identifies this as an XML
124document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire 126document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
125guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 127guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
126Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 128Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.9

  ViewVC Help
Powered by ViewVC 1.1.20