/[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>
21<title>Guide XML design goals</title> 21<title>Guide XML design goals</title>
22<body> 22<body>
23 23
24<p> The guide XML syntax is lightweight yet expressive, so that it is easy to 24<p> The guide XML syntax is lightweight yet expressive, so that it is easy to
25learn yet also provides all the features we need for the creation of web 25learn yet also provides all the features we need for the creation of web
26documentation. The number of tags is kept to a minimum -- just those we need. 26documentation. The number of tags is kept to a minimum -- just those we need.
27This makes it easy to transform guide into other formats, such as DocBook 27This makes it easy to transform guide into other formats, such as DocBook
28XML/SGML or web-ready HTML. </p> 28XML/SGML or web-ready HTML. </p>
29 29
30<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML 30<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
31documents.</p> 31documents.</p>
32 32
33</body> 33</body>
34</section> 34</section>
35 35
36<section> 36<section>
37<title>How to transform guide XML into HTML</title> 37<title>How to transform guide XML into HTML</title>
38<body> 38<body>
39 39
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>
88</chapter> 94</chapter>
89<chapter> 95<chapter>
90 <title>Guide XML</title> 96 <title>Guide XML</title>
91<section> 97<section>
92<title>Basic structure</title> 98<title>Basic structure</title>
93<body> 99<body>
94 100
95<p>Now that you know how to transform guide XML, you're ready to start learning 101<p>Now that you know how to transform guide XML, you're ready to start learning
96the guide XML syntax. We'll start with the the initial tags used in a guide 102the guide XML syntax. We'll start with the the initial tags used in a guide
97XML document: </p> 103XML document: </p>
103&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt; 109&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt;
104 <i>Daniel Robbins</i>&lt;/mail&gt; 110 <i>Daniel Robbins</i>&lt;/mail&gt;
105&lt;/author&gt; 111&lt;/author&gt;
106&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt; 112&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
107 <i>Thomas Flavel</i>&lt;/mail&gt; 113 <i>Thomas Flavel</i>&lt;/mail&gt;
108&lt;/author&gt; 114&lt;/author&gt;
109 115
110&lt;abstract&gt;<i>This guide shows you how to compose web documentation using 116&lt;abstract&gt;<i>This guide shows you how to compose web documentation using
111our new lightweight Gentoo guide XML syntax. This syntax is the official 117our new lightweight Gentoo guide XML syntax. This syntax is the official
112format for Gentoo Linux web documentation, and this document itself was created 118format for Gentoo Linux web documentation, and this document itself was created
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
127guide document. </p> 129guide document. </p>
128 130
129<p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 131<p>Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
130about the various authors of the document. Each <c>&lt;author&gt;</c> tag 132about the various authors of the document. Each <c>&lt;author&gt;</c> tag
131allows for an optional <c>title=</c> element, used to specify the author's 133allows for an optional <c>title=</c> element, used to specify the author's
132relationship to the document (author, co-author, editor, etc.). In this 134relationship to the document (author, co-author, editor, etc.). In this
133particular example, the authors' names are enclosed in another tag -- a 135particular example, the authors' names are enclosed in another tag -- a
134<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular 136<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
135person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no 137person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
136more than one <c>&lt;author&gt;</c> element is required per guide document. 138more than one <c>&lt;author&gt;</c> element is required per guide document.

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

  ViewVC Help
Powered by ViewVC 1.1.20