/[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.3 Revision 1.14
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 3
6<guide link="/doc/en/xml-guide.xml"> 4<guide link="/doc/en/xml-guide.xml">
7<title>Gentoo Linux Documentation Guide</title> 5<title>Gentoo Linux XML Guide</title>
8<author title="Chief Architect"><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="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
8<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>
9
10<license/>
9 11
10<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide 12<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide
11XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document 13XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document
12itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. 14itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML.
13</abstract> 15</abstract>
14 16
15<version>1.0</version> 17<version>2.0</version>
16<date>07 Mar 2002</date> 18<date>4th of August 2003</date>
17 19
18<chapter> 20<chapter>
19<title>Guide basics</title> 21<title>Guide basics</title>
20 22
21<section> 23<section>
38<title>How to transform guide XML into HTML</title> 40<title>How to transform guide XML into HTML</title>
39<body> 41<body>
40 42
41<p> Before we take a look at the guide syntax itself, it's helpful to know how 43<p> Before we take a look at the guide syntax itself, it's helpful to know how
42guide XML is transformed into web-ready HTML. To do this, we use a special 44guide XML is transformed into web-ready HTML. To do this, we use a special
43file called <path>guide-main.xsl</path>, along with a command-line XSLT processing 45file called <path>guide.xsl</path>, along with a command-line XSLT processing
44tool (also called an "engine"). The <path>guide-main.xsl</path> file describes 46tool (also called an "engine"). The <path>guide.xsl</path> file describes
45exactly how to transform the contents of the source guide XML document to 47exactly how to transform the contents of the source guide XML document to
46create the target HTML file. Two popular XSLT processors are <c>sabcmd</c> 48create the target HTML file. The processing tool that Gentoo Linux uses
47(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c> 49is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. </p>
48(found in the <path>dev-libs/libxslt</path> package). From experience, we've
49found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
50processor. </p>
51 50
52<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're
53ready to convert guide XML into web-ready HTML. Here's how it works. First,
54download the latest snapshot of our Web site from
55<uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri
56link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri>
57file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path>
58directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find
59<path>gentoo-src/xml/install.xml</path>. (The new user installation guide).
60This will be our source XML guide document. The easiest way to perform the
61transformation is to change directories to the location of the
62<path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
63</p>
64 51
52<pre caption="Installing libxslt">
53# <c>emerge libxslt</c>
65<pre> 54</pre>
66# <i>cd gentoo-web/xsl</i> 55
56<p>Now that we have the way, we need the means, so to speak. In other words,
57we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
58that are available for download: </p>
59
60<p><b>The first type contains the entire up-to-date Gentoo Linux website</b>.
61Included are our XSL templates, so if you are planning to transform any documentation,
62you will need this tarball. The tarball can be found
63<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.</p>
64
65<p><b>The second type contains daily snapshots our XML documentation source</b> in
66every language that we offer. Please note that it is impossible to transform
67documentation with this tarball, so please download the web tarball if you want to fully
68develop your own documentation. These tarballs are especially useful for translators.
69These tarballs can be found <uri link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
70</p>
71
72<p>After the web tarball is downloaded and extracted, go
73to the directory where the tarball was extracted, and enter the
74<path>htdocs</path> directory. Browse around and get comfortable with the
75layout, but note the <path>xsl</path> and <path>doc</path> directories.
76As you might have guessed, the XSL stylesheets are in <path>xsl</path>,
77and our documentation is in <path>doc</path>. For testing purposes, we
78will be using the Gentoo Linux CD Installation Guide, located at
79<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations
80of the XSL and XML file are known, we can do some transforming with
81<c>xsltproc</c>. </p>
82
83<pre caption="Transforming gentoo-x86-install.xml">
67# <i>xsltproc guide-main.xsl ../xml/install.xml &gt; /tmp/install.html</i> 84# <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c>
68</pre> 85</pre>
69 86
70<p> If all went well, you should have a web-ready version of 87<p> If all went well, you should have a web-ready version of
71<path>install.xml</path> at <path>/tmp/install.html</path>. For this document 88<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document
72to display properly in a web browser, you may have to copy some files from 89to display properly in a web browser, you may have to copy some files from
73<path>gentoo-web</path> to <path>/tmp</path>, such 90<path>htdocs</path> to <path>/tmp</path>, such
74as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path> 91as <path>css/main.css</path> and (to be safe) the entire <path>images</path>
75directory. 92directory.
76</p> 93</p>
77 94
78</body> 95</body>
79</section> 96</section>
87<p>Now that you know how to transform guide XML, you're ready to start learning 104<p>Now that you know how to transform guide XML, you're ready to start learning
88the guide XML syntax. We'll start with the the initial tags used in a guide 105the guide XML syntax. We'll start with the the initial tags used in a guide
89XML document: </p> 106XML document: </p>
90 107
91<pre caption="The initial part of a guide XML document"> 108<pre caption="The initial part of a guide XML document">
92&lt;?xml version='1.0'?&gt; 109&lt;?xml version='1.0' encoding="UTF-8"?&gt;
93&lt;guide&gt; 110&lt;guide link="relative_link_to_your_guide"&gt;
94&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 111&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
95&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt; 112&lt;author title="<i>Chief Architect</i>"&gt;&lt;mail link="<i>drobbins@gentoo.org</i>"&gt;
96 <i>Daniel Robbins</i>&lt;/mail&gt; 113 <i>Daniel Robbins</i>&lt;/mail&gt;
97&lt;/author&gt; 114&lt;/author&gt;
98&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt; 115&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
101 118
102&lt;abstract&gt;<i>This guide shows you how to compose web documentation using 119&lt;abstract&gt;<i>This guide shows you how to compose web documentation using
103our new lightweight Gentoo guide XML syntax. This syntax is the official 120our new lightweight Gentoo guide XML syntax. This syntax is the official
104format for Gentoo Linux web documentation, and this document itself was created 121format for Gentoo Linux web documentation, and this document itself was created
105using guide XML.</i> &lt;/abstract&gt; 122using guide XML.</i> &lt;/abstract&gt;
123
124&lt;license/&gt;
106 125
107&lt;version&gt;<i>1.0</i>&lt;/version&gt; 126&lt;version&gt;<i>1.0</i>&lt;/version&gt;
108&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt; 127&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt;
109</pre> 128</pre>
110 129
130respectively. This rounds out the tags that should appear at the beginning of 149respectively. This rounds out the tags that should appear at the beginning of
131a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> 150a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c>
132tags, these tags shouldn't appear anywhere else except immediately inside the 151tags, these tags shouldn't appear anywhere else except immediately inside the
133<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 152<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
134required) that these tags appear before the content of the document. </p> 153required) that these tags appear before the content of the document. </p>
154
155<p>Finally we have the <c>&lt;license/&gt;</c> tag, used to publish the
156document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
157Commons - Attribution / Share Alike</uri> license as required by the <uri
158link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
159 </p>
135 160
136</body> 161</body>
137</section> 162</section>
138 163
139<section> 164<section>
237Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit), 262Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
238these are the only tags that should appear immediately inside a 263these are the only tags that should appear immediately inside a
239<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be 264<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
240stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a 265stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
241<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 266<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
242preserves its whitespace exactly, making it well-suited for code excerpts.</p> 267preserves its whitespace exactly, making it well-suited for code excerpts.
268You can also name the <c>&lt;pre&gt;</c> tag:</p>
269
270<pre caption = "Named &lt;pre&gt;">
271&lt;pre caption = "Output of uptime"&gt;
272# &lt;i&gt;uptime&lt;/i&gt;
27316:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
274&lt;/pre&gt;
275</pre>
243 276
244</body> 277</body>
245</section> 278</section>
246<section> 279<section>
247<title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title> 280<title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title>
358 <body> 391 <body>
359 <p>Guide has been specially designed to be "lean and mean" so that developers 392 <p>Guide has been specially designed to be "lean and mean" so that developers
360 can spend more time writing documentation and less time learning the actual XML 393 can spend more time writing documentation and less time learning the actual XML
361 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 394 syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
362 to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please 395 to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please
363 post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail> 396 post a message to the <mail link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail>
364 stating what you'd like to tackle. 397 stating what you'd like to tackle.
365 Have fun!</p> 398 Have fun!</p>
366 </body> 399 </body>
367</section> 400</section>
368</chapter> 401</chapter>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.14

  ViewVC Help
Powered by ViewVC 1.1.20