/[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.7
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 Documentation 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="Editor"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
9 8
10<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
11XML 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
12itself 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.
13</abstract> 12</abstract>
14 13
15<version>1.0</version> 14<version>1.1</version>
16<date>07 Mar 2002</date> 15<date>10 January 2002</date>
17 16
18<chapter> 17<chapter>
19<title>Guide basics</title> 18<title>Guide basics</title>
20 19
21<section> 20<section>
38<title>How to transform guide XML into HTML</title> 37<title>How to transform guide XML into HTML</title>
39<body> 38<body>
40 39
41<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
42guide 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
43file called <path>guide-main.xsl</path>, along with a command-line XSLT processing 42file 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 43tool (also called an "engine"). The <path>guide.xsl</path> file describes
45exactly 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
46create the target HTML file. Two popular XSLT processors are <c>sabcmd</c> 45create the target HTML file. Two popular XSLT processors are <c>sabcmd</c>
47(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c> 46(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c>
48(found in the <path>dev-libs/libxslt</path> package). From experience, we've 47(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 48found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
50processor. </p> 49processor. </p>
51 50
51
52<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're 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, 53ready to convert guide XML into web-ready HTML. In order to do this though,
54download the latest snapshot of our Web site from 54it is necessary to get the latest snapshot of our website tree.
55<uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri 55</p>
56link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri> 56
57<p>The gzipped tarball for the website can be found
58<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
59</p>
60
61<note>You can now download the full set of Gentoo Linux documentation for your language
62of choice without having to download the full web tree. Please navigate to
63<uri>http://www.gentoo.org/dyn/doc-snapshots</uri> to find the tarballs.
64</note>
65
57file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path> 66<p>Now, extract the tarball. Inside it, you'll find a <path>htdocs</path>
58directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find 67directory. Now, find <path>htdocs/doc/&lt;your lang&gt;/gentoo-x86-install.xml</path>
59<path>gentoo-src/xml/install.xml</path>. (The new user installation guide). 68(The new user installation guide). This will be our source XML guide document.
60This will be our source XML guide document. The easiest way to perform the
61transformation is to change directories to the location of the 69The easiest way to perform the transformation is to change directories to the location of the
62<path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows: 70<path>guide.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
63</p> 71</p>
64 72
65<pre> 73<pre caption="Transforming gentoo-x86-install.xml">
66# <i>cd gentoo-web/xsl</i> 74# <c>cd gentoo-web/xsl</c>
67# <i>xsltproc guide-main.xsl ../xml/install.xml &gt; /tmp/install.html</i> 75# <c>xsltproc guide.xsl ../doc/&lt;your lang&gt;/gentoo-x86-install.xml &gt; /tmp/install.html</c>
68</pre> 76</pre>
69 77
70<p> If all went well, you should have a web-ready version of 78<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 79<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 80to display properly in a web browser, you may have to copy some files from
73<path>gentoo-web</path> to <path>/tmp</path>, such 81<path>htdocs</path> to <path>/tmp</path>, such
74as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path> 82as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path>
75directory. 83directory.
76</p> 84</p>
77 85
78</body> 86</body>
87<p>Now that you know how to transform guide XML, you're ready to start learning 95<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 96the guide XML syntax. We'll start with the the initial tags used in a guide
89XML document: </p> 97XML document: </p>
90 98
91<pre caption="The initial part of a guide XML document"> 99<pre caption="The initial part of a guide XML document">
92&lt;?xml version='1.0'?&gt; 100&lt;?xml version='1.0' encoding="UTF-8"?&gt;
93&lt;guide&gt; 101&lt;guide link="relative_link_to_your_guide"&gt;
94&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 102&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; 103&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; 104 <i>Daniel Robbins</i>&lt;/mail&gt;
97&lt;/author&gt; 105&lt;/author&gt;
98&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt; 106&lt;author title="<i>Editor</i>"&gt;&lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;
99 <i>Thomas Flavel</i>&lt;/mail&gt; 107 <i>Thomas Flavel</i>&lt;/mail&gt;
100&lt;/author&gt; 108&lt;/author&gt;
109
110<impo>If you are going to be submitting documents, it is necessary to read the
111<uri link="http://www.gentoo.org/doc/en/doc-developer-guide.xml">Gentoo Documentation Developer's Policy</uri>.
112</impo>
101 113
102&lt;abstract&gt;<i>This guide shows you how to compose web documentation using 114&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 115our new lightweight Gentoo guide XML syntax. This syntax is the official
104format for Gentoo Linux web documentation, and this document itself was created 116format for Gentoo Linux web documentation, and this document itself was created
105using guide XML.</i> &lt;/abstract&gt; 117using guide XML.</i> &lt;/abstract&gt;
359 <p>Guide has been specially designed to be "lean and mean" so that developers 371 <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 372 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" 373 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 374 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> 375 post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail>
376 and <mail link="gentoo-doc@gentoo.org">the gentoo-doc mailing list</mail>
364 stating what you'd like to tackle. 377 stating what you'd like to tackle.
365 Have fun!</p> 378 Have fun!</p>
366 </body> 379 </body>
367</section> 380</section>
368</chapter> 381</chapter>

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

  ViewVC Help
Powered by ViewVC 1.1.20