/[gentoo]/xml/htdocs/proj/en/glep/glep-0013.html
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0013.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.4
6PEP, see http://www.python.org/peps/pep-0001.html for instructions and links 6PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! 7to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8--> 8-->
9<head> 9<head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" /> 11 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 <title>GLEP 13 -- Providing the users with a Gentoo Handbook</title> 12 <title>GLEP 13 -- Providing the users with a Gentoo Handbook</title>
13 <link rel="stylesheet" href="tools/glep.css" type="text/css" /> 13 <style type="text/css">
14
15/*
16:Author: David Goodger
17:Contact: goodger@users.sourceforge.net
18:date: $Date: 2007/01/25 03:26:26 $
19:version: $Revision: 1.4 $
20:copyright: This stylesheet has been placed in the public domain.
21
22Default cascading style sheet for the PEP HTML output of Docutils.
23*/
24
25.first {
26 margin-top: 0 }
27
28.last {
29 margin-bottom: 0 }
30
31.navigation {
32 width: 100% ;
33 background: #cc99ff ;
34 margin-top: 0px ;
35 margin-bottom: 0px }
36
37.navigation .navicon {
38 width: 150px ;
39 height: 35px }
40
41.navigation .textlinks {
42 padding-left: 1em ;
43 text-align: left }
44
45.navigation td, .navigation th {
46 padding-left: 0em ;
47 padding-right: 0em ;
48 vertical-align: middle }
49
50.rfc2822 {
51 margin-top: 0.5em ;
52 margin-left: 0.5em ;
53 margin-right: 0.5em ;
54 margin-bottom: 0em }
55
56.rfc2822 td {
57 text-align: left }
58
59.rfc2822 th.field-name {
60 text-align: right ;
61 font-family: sans-serif ;
62 padding-right: 0.5em ;
63 font-weight: bold ;
64 margin-bottom: 0em }
65
66a.toc-backref {
67 text-decoration: none ;
68 color: black }
69
70body {
71 margin: 0px ;
72 margin-bottom: 1em ;
73 padding: 0px }
74
75dd {
76 margin-bottom: 0.5em }
77
78div.section {
79 margin-left: 1em ;
80 margin-right: 1em ;
81 margin-bottom: 1.5em }
82
83div.section div.section {
84 margin-left: 0em ;
85 margin-right: 0em ;
86 margin-top: 1.5em }
87
88div.abstract {
89 margin: 2em 5em }
90
91div.abstract p.topic-title {
92 font-weight: bold ;
93 text-align: center }
94
95div.attention, div.caution, div.danger, div.error, div.hint,
96div.important, div.note, div.tip, div.warning {
97 margin: 2em ;
98 border: medium outset ;
99 padding: 1em }
100
101div.attention p.admonition-title, div.caution p.admonition-title,
102div.danger p.admonition-title, div.error p.admonition-title,
103div.warning p.admonition-title {
104 color: red ;
105 font-weight: bold ;
106 font-family: sans-serif }
107
108div.hint p.admonition-title, div.important p.admonition-title,
109div.note p.admonition-title, div.tip p.admonition-title {
110 font-weight: bold ;
111 font-family: sans-serif }
112
113div.figure {
114 margin-left: 2em }
115
116div.footer, div.header {
117 font-size: smaller }
118
119div.footer {
120 margin-left: 1em ;
121 margin-right: 1em }
122
123div.system-messages {
124 margin: 5em }
125
126div.system-messages h1 {
127 color: red }
128
129div.system-message {
130 border: medium outset ;
131 padding: 1em }
132
133div.system-message p.system-message-title {
134 color: red ;
135 font-weight: bold }
136
137div.topic {
138 margin: 2em }
139
140h1 {
141 font-family: sans-serif ;
142 font-size: large }
143
144h2 {
145 font-family: sans-serif ;
146 font-size: medium }
147
148h3 {
149 font-family: sans-serif ;
150 font-size: small }
151
152h4 {
153 font-family: sans-serif ;
154 font-style: italic ;
155 font-size: small }
156
157h5 {
158 font-family: sans-serif;
159 font-size: x-small }
160
161h6 {
162 font-family: sans-serif;
163 font-style: italic ;
164 font-size: x-small }
165
166.section hr {
167 width: 75% }
168
169ol.simple, ul.simple {
170 margin-bottom: 1em }
171
172ol.arabic {
173 list-style: decimal }
174
175ol.loweralpha {
176 list-style: lower-alpha }
177
178ol.upperalpha {
179 list-style: upper-alpha }
180
181ol.lowerroman {
182 list-style: lower-roman }
183
184ol.upperroman {
185 list-style: upper-roman }
186
187p.caption {
188 font-style: italic }
189
190p.credits {
191 font-style: italic ;
192 font-size: smaller }
193
194p.label {
195 white-space: nowrap }
196
197p.topic-title {
198 font-family: sans-serif ;
199 font-weight: bold }
200
201pre.line-block {
202 font-family: serif ;
203 font-size: 100% }
204
205pre.literal-block, pre.doctest-block {
206 margin-left: 2em ;
207 margin-right: 2em ;
208 background-color: #eeeeee }
209
210span.classifier {
211 font-family: sans-serif ;
212 font-style: oblique }
213
214span.classifier-delimiter {
215 font-family: sans-serif ;
216 font-weight: bold }
217
218span.interpreted {
219 font-family: sans-serif }
220
221span.option-argument {
222 font-style: italic }
223
224span.pre {
225 white-space: pre }
226
227span.problematic {
228 color: red }
229
230table {
231 margin-top: 0.5em ;
232 margin-bottom: 0.5em }
233
234td, th {
235 padding-left: 0.5em ;
236 padding-right: 0.5em ;
237 vertical-align: top }
238
239td.num {
240 text-align: right }
241
242th.field-name {
243 font-weight: bold ;
244 text-align: left ;
245 white-space: nowrap }
246
247h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248 font-size: 100% }
249
250tt {
251 background-color: #eeeeee }
252
253ul.auto-toc {
254 list-style-type: none }
255
256</style>
14</head> 257</head>
15<body bgcolor="white"> 258<body bgcolor="white">
16<table class="navigation" cellpadding="0" cellspacing="0" 259<table class="navigation" cellpadding="0" cellspacing="0"
17 width="100%" border="0"> 260 width="100%" border="0">
18<tr><td class="navicon" width="150" height="35"> 261<tr><td class="navicon" width="150" height="35">
19<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page"> 262<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
20<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]" 263<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21 border="0" width="150" height="35" /></a></td> 264 border="0" width="150" height="35" /></a></td>
22<td class="textlinks" align="left"> 265<td class="textlinks" align="left">
23[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>] 266[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>] 267[<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
25[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0013.txt">GLEP Source</a></b>] 268[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0013.txt">GLEP Source</a></b>]
26</td></tr></table> 269</td></tr></table>
27<div class="document">
28<table class="rfc2822 field-list" frame="void" rules="none"> 270<table class="rfc2822 docutils field-list" frame="void" rules="none">
29<col class="field-name" /> 271<col class="field-name" />
30<col class="field-body" /> 272<col class="field-body" />
31<tbody valign="top"> 273<tbody valign="top">
32<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">13</td> 274<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">13</td>
33</tr> 275</tr>
34<tr class="field"><th class="field-name">Title:</th><td class="field-body">Providing the users with a Gentoo Handbook</td> 276<tr class="field"><th class="field-name">Title:</th><td class="field-body">Providing the users with a Gentoo Handbook</td>
35</tr> 277</tr>
36<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td> 278<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
37</tr> 279</tr>
38<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0013.txt?cvsroot=gentoo">2003/08/20 02:28:47</a></td> 280<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0013.txt?cvsroot=gentoo">2004/10/26 00:21:28</a></td>
39</tr> 281</tr>
40<tr class="field"><th class="field-name">Author:</th><td class="field-body">Sven Vermeulen &lt;swift&#32;&#97;t&#32;gentoo.org&gt;</td> 282<tr class="field"><th class="field-name">Author:</th><td class="field-body">Sven Vermeulen &lt;swift&#32;&#97;t&#32;gentoo.org&gt;</td>
41</tr> 283</tr>
42<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> 284<tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
43</tr> 285</tr>
44<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> 286<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
45</tr> 287</tr>
46<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td> 288<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
47</tr> 289</tr>
48<tr class="field"><th class="field-name">Created:</th><td class="field-body">15 Aug 2003</td> 290<tr class="field"><th class="field-name">Created:</th><td class="field-body">15 Aug 2003</td>
49</tr> 291</tr>
50<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">19-Aug-2003</td> 292<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">19-Aug-2003 25-Oct-2004</td>
51</tr> 293</tr>
52</tbody> 294</tbody>
53</table> 295</table>
54<hr /> 296<hr />
55<div class="contents topic" id="contents"> 297<div class="contents topic">
56<p class="topic-title"><a name="contents">Contents</a></p> 298<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
57<ul class="simple"> 299<ul class="simple">
58<li><a class="reference" href="#abstract" id="id9" name="id9">Abstract</a></li> 300<li><a class="reference" href="#abstract" id="id9" name="id9">Abstract</a></li>
59<li><a class="reference" href="#motivation" id="id10" name="id10">Motivation</a></li> 301<li><a class="reference" href="#motivation" id="id10" name="id10">Motivation</a></li>
60<li><a class="reference" href="#rationale" id="id11" name="id11">Rationale</a></li> 302<li><a class="reference" href="#rationale" id="id11" name="id11">Rationale</a></li>
61<li><a class="reference" href="#implementation" id="id12" name="id12">Implementation</a><ul> 303<li><a class="reference" href="#implementation" id="id12" name="id12">Implementation</a><ul>
70<li><a class="reference" href="#reference-implementation" id="id19" name="id19">Reference Implementation</a></li> 312<li><a class="reference" href="#reference-implementation" id="id19" name="id19">Reference Implementation</a></li>
71<li><a class="reference" href="#references" id="id20" name="id20">References</a></li> 313<li><a class="reference" href="#references" id="id20" name="id20">References</a></li>
72<li><a class="reference" href="#copyright" id="id21" name="id21">Copyright</a></li> 314<li><a class="reference" href="#copyright" id="id21" name="id21">Copyright</a></li>
73</ul> 315</ul>
74</div> 316</div>
75<div class="section" id="abstract"> 317<div class="section">
76<h1><a class="toc-backref" href="#id9" name="abstract">Abstract</a></h1> 318<h1><a class="toc-backref" href="#id9" id="abstract" name="abstract">Abstract</a></h1>
77<p>This GLEP provides a vision on the evolution of the Gentoo Documentation, 319<p>This GLEP provides a vision on the evolution of the Gentoo Documentation,
78namely a handbook-like document that provides its readers documentation about 320namely a handbook-like document that provides its readers documentation about
79every aspect of the Gentoo distribution: installation, administration, 321every aspect of the Gentoo distribution: installation, administration,
80application usage, development etc.</p> 322application usage, development etc.</p>
81</div> 323</div>
82<div class="section" id="motivation"> 324<div class="section">
83<h1><a class="toc-backref" href="#id10" name="motivation">Motivation</a></h1> 325<h1><a class="toc-backref" href="#id10" id="motivation" name="motivation">Motivation</a></h1>
84<p>Gentoo's current Installation Guide <a class="footnote-reference" href="#instguide" id="id1" name="id1">[1]</a> is rapidly growing, being 326<p>Gentoo's current Installation Guide <a class="footnote-reference" href="#instguide" id="id1" name="id1">[1]</a> is rapidly growing, being
85extended with more and more features that the Gentoo users can help with their 327extended with more and more features that the Gentoo users can help with their
86quest for the perfect installation. This increase is needed and a Good Thing, 328quest for the perfect installation. This increase is needed and a Good Thing,
87but it makes the guide less easy to read or use as reference.</p> 329but it makes the guide less easy to read or use as reference.</p>
88<p>There is no reason whatsoever that this evolution will stagnate, on the 330<p>There is no reason whatsoever that this evolution will stagnate, on the
92steps (with a few differences). I myself even hope to merge our LVM Guide 334steps (with a few differences). I myself even hope to merge our LVM Guide
93<a class="footnote-reference" href="#lvm" id="id3" name="id3">[3]</a> into the Installation Guide as I believe several of our users would 335<a class="footnote-reference" href="#lvm" id="id3" name="id3">[3]</a> into the Installation Guide as I believe several of our users would
94love to use LVM on their machines, but currently don't because they don't know 336love to use LVM on their machines, but currently don't because they don't know
95how handy and easy it is -- you all know this feeling :)</p> 337how handy and easy it is -- you all know this feeling :)</p>
96</div> 338</div>
97<div class="section" id="rationale"> 339<div class="section">
98<h1><a class="toc-backref" href="#id11" name="rationale">Rationale</a></h1> 340<h1><a class="toc-backref" href="#id11" id="rationale" name="rationale">Rationale</a></h1>
99<p>To address the beforementioned problem, there are two ideas:</p> 341<p>To address the beforementioned problem, there are two ideas:</p>
100<ul class="simple"> 342<ul class="simple">
101<li>Split the Installation Guide into several independent guides. For instance, 343<li>Split the Installation Guide into several independent guides. For instance,
102we can move the information regarding the kernelconfiguration into the 344we can move the information regarding the kernelconfiguration into the
103Kernel Guide, create a partitioning-howto that decribes the fdisk (and 345Kernel Guide, create a partitioning-howto that decribes the fdisk (and
112document, our users receive a fully integrated document that embraces 354document, our users receive a fully integrated document that embraces
113everything he or she wants to know. It will also make it more easy to provide 355everything he or she wants to know. It will also make it more easy to provide
114printable documentation (in PDF or other form) without loosing the comfort of 356printable documentation (in PDF or other form) without loosing the comfort of
115having the installation documents online and on the LiveCDs.</p> 357having the installation documents online and on the LiveCDs.</p>
116</div> 358</div>
117<div class="section" id="implementation"> 359<div class="section">
118<h1><a class="toc-backref" href="#id12" name="implementation">Implementation</a></h1> 360<h1><a class="toc-backref" href="#id12" id="implementation" name="implementation">Implementation</a></h1>
119<p>To implement such a handbook, the Gentoo Documentation Project <a class="footnote-reference" href="#gdp" id="id5" name="id5">[5]</a> needs a 361<p>To implement such a handbook, the Gentoo Documentation Project <a class="footnote-reference" href="#gdp" id="id5" name="id5">[5]</a> needs a
120rewritten stylesheet for its GuideXML <a class="footnote-reference" href="#guidexml" id="id6" name="id6">[6]</a> format. Since there are no 362rewritten stylesheet for its GuideXML <a class="footnote-reference" href="#guidexml" id="id6" name="id6">[6]</a> format. Since there are no
121problems with GuideXML itself, and since it is very flexible in its use, the 363problems with GuideXML itself, and since it is very flexible in its use, the
122recommendation to stick with GuideXML is clear. We do need some extra features 364recommendation to stick with GuideXML is clear. We do need some extra features
123in GuideXML, without breaking the current GuideXML implementation.</p> 365in GuideXML, without breaking the current GuideXML implementation.</p>
124<p>This last thing is important, since implementing this handbook-like document 366<p>This last thing is important, since implementing this handbook-like document
125should be done parallel to the development of our current documentation: 367should be done parallel to the development of our current documentation:
126developing the Gentoo Handbook takes a long time and we don't want to force 368developing the Gentoo Handbook takes a long time and we don't want to force
127our users to use a non-usable document.</p> 369our users to use a non-usable document.</p>
128<p>After improving the GuideXML format, the first things that need to be 370<p>After improving the GuideXML format, the first things that need to be
129addressed are the installation instructions. They should be merged with other, 371addressed are the installation instructions. They should be merged with other,
130existing guides that inform the user with installation-specific items (such as 372existing guides that inform the user with installation-specific items (such as
131the Aternative Installation Guide, LVM Guide, Platform-specific Installation 373the Aternative Installation Guide, LVM Guide, Platform-specific Installation
132Guides, etc.</p> 374Guides, etc.</p>
133<p>Other chapters that need to be put in place are:</p> 375<p>Other chapters that need to be put in place are:</p>
134<ul class="simple"> 376<ul class="simple">
135<li>A chapter on Gentoo Development, which embraces all current 377<li>A chapter on Gentoo Development, which embraces all current
136development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo 378development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo
137Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been 379Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been
138frequently asked by the Gentoo ebuild maintainers and several other Gentoo 380frequently asked by the Gentoo ebuild maintainers and several other Gentoo
139Developers.</li> 381Developers.</li>
140<li>A chapter specific to System Administration, such as Mailserver 382<li>A chapter specific to System Administration, such as Mailserver
141Administration, User Administration, Printing Administration etc. We already 383Administration, User Administration, Printing Administration etc. We already
142have several guides that describe parts of these items.</li> 384have several guides that describe parts of these items.</li>
143<li>A chapter specific to Gentoo Usage, including our popular Desktop 385<li>A chapter specific to Gentoo Usage, including our popular Desktop
144Configuration Guide <a class="footnote-reference" href="#desktop" id="id7" name="id7">[7]</a> and several Application-specific guides.</li> 386Configuration Guide <a class="footnote-reference" href="#desktop" id="id7" name="id7">[7]</a> and several Application-specific guides.</li>
145</ul> 387</ul>
146<p>The following sections describe these steps more in detail...</p> 388<p>The following sections describe these steps more in detail...</p>
147<div class="section" id="extending-guidexml"> 389<div class="section">
148<h2><a class="toc-backref" href="#id13" name="extending-guidexml">Extending GuideXML</a></h2> 390<h2><a class="toc-backref" href="#id13" id="extending-guidexml" name="extending-guidexml">Extending GuideXML</a></h2>
149<p>The GuideXML format should be extended with the following items:</p> 391<p>The GuideXML format should be extended with the following items:</p>
150<ul class="simple"> 392<ul class="simple">
151<li>More depth regarding information-divisions.</li> 393<li>More depth regarding information-divisions.</li>
152<li>&quot;Including&quot; external sourcecode</li> 394<li>&quot;Including&quot; external sourcecode</li>
153<li>Easier in-document references</li> 395<li>Easier in-document references</li>
157<pre class="literal-block"> 399<pre class="literal-block">
158&lt;guide&gt; 400&lt;guide&gt;
159 &lt;chapter&gt; 401 &lt;chapter&gt;
160 &lt;section&gt; 402 &lt;section&gt;
161</pre> 403</pre>
162<p>The <tt class="literal"><span class="pre">&lt;guide&gt;</span></tt> tag is currently a one-time tag: it defines the start of the 404<p>The <tt class="docutils literal"><span class="pre">&lt;guide&gt;</span></tt> tag is currently a one-time tag: it defines the start of the
163guide, and ofcourse the guide ends with <tt class="literal"><span class="pre">&lt;/guide&gt;</span></tt>. 405guide, and ofcourse the guide ends with <tt class="docutils literal"><span class="pre">&lt;/guide&gt;</span></tt>.
164The <tt class="literal"><span class="pre">&lt;chapter&gt;</span></tt> tag divides the document into seperate chapters. However, 406The <tt class="docutils literal"><span class="pre">&lt;chapter&gt;</span></tt> tag divides the document into seperate chapters. However,
165most of our documents have small chapters, whereas normal books and documents 407most of our documents have small chapters, whereas normal books and documents
166have chapters that encompasses several pages. 408have chapters that encompasses several pages.
167The <tt class="literal"><span class="pre">&lt;section&gt;</span></tt> tag further divides the chapter in which it resides.</p> 409The <tt class="docutils literal"><span class="pre">&lt;section&gt;</span></tt> tag further divides the chapter in which it resides.</p>
168<p>This means that our current installation guides have a division-depth of 2: 410<p>This means that our current installation guides have a division-depth of 2:
169you can define a chapter, and in that chapter make subdivisions with 411you can define a chapter, and in that chapter make subdivisions with
170<tt class="literal"><span class="pre">&lt;section&gt;</span></tt>. This is however insufficient for a handbook-like document. To 412<tt class="docutils literal"><span class="pre">&lt;section&gt;</span></tt>. This is however insufficient for a handbook-like document. To
171improve the GuideXML, we can add <tt class="literal"><span class="pre">&lt;subsection&gt;</span></tt> and, if needed, 413improve the GuideXML, we can add <tt class="docutils literal"><span class="pre">&lt;subsection&gt;</span></tt> and, if needed,
172<tt class="literal"><span class="pre">&lt;subsubsection&gt;</span></tt>, based on LaTeX's divisions.</p> 414<tt class="docutils literal"><span class="pre">&lt;subsubsection&gt;</span></tt>, based on LaTeX's divisions.</p>
173<p>Another requisite is to be able to include external documents. Without this 415<p>Another requisite is to be able to include external documents. Without this
174possibility, maintaining the handbook would be cumbersome to say the least. 416possibility, maintaining the handbook would be cumbersome to say the least.
175XSLT (which is used to process the GuideXML files) can easily provide this, so 417XSLT (which is used to process the GuideXML files) can easily provide this, so
176there are no specific needs to include this feature.</p> 418there are no specific needs to include this feature.</p>
177<p>A possible tag would be <tt class="literal"><span class="pre">&lt;include</span> <span class="pre">file=&quot;foobar.xml&quot;</span> <span class="pre">/&gt;</span></tt>.</p> 419<p>A possible tag would be <tt class="docutils literal"><span class="pre">&lt;include</span> <span class="pre">file=&quot;foobar.xml&quot;</span> <span class="pre">/&gt;</span></tt>.</p>
178<p>With such a division, we could have each chapter inside its own document, 420<p>With such a division, we could have each chapter inside its own document,
179making maintenance far more easy.</p> 421making maintenance far more easy.</p>
180<p>The final implementation is in-document references. Currently, the Gentoo 422<p>The final implementation is in-document references. Currently, the Gentoo
181Documentation Developers have so guess in what chapter a certain section 423Documentation Developers have so guess in what chapter a certain section
182resides, and what section we are actually discussing: <tt class="literal"><span class="pre">#doc_chap4_sect3</span></tt> 424resides, and what section we are actually discussing: <tt class="docutils literal"><span class="pre">#doc_chap4_sect3</span></tt>
183provides us with a link to chapter 4, section 3. This is a workable 425provides us with a link to chapter 4, section 3. This is a workable
184implementation for small documents, but impossible for handbooks.</p> 426implementation for small documents, but impossible for handbooks.</p>
185<p>Implementing a more HTML-alike reference inside the division-tags would be 427<p>Implementing a more HTML-alike reference inside the division-tags would be
186preferable: <tt class="literal"><span class="pre">&lt;chapter</span> <span class="pre">name=&quot;installation&quot;&gt;</span></tt>, <tt class="literal"><span class="pre">&lt;section</span> 428preferable: <tt class="docutils literal"><span class="pre">&lt;chapter</span> <span class="pre">name=&quot;installation&quot;&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;section</span>
187<span class="pre">name=&quot;partitioning&quot;&gt;</span></tt> etc. Refering would then be <tt class="literal"><span class="pre">#installation</span></tt> and 429<span class="pre">name=&quot;partitioning&quot;&gt;</span></tt> etc. Refering would then be <tt class="docutils literal"><span class="pre">#installation</span></tt> and
188<tt class="literal"><span class="pre">#partitioning</span></tt> respectively.</p> 430<tt class="docutils literal"><span class="pre">#partitioning</span></tt> respectively.</p>
189</div> 431</div>
190<div class="section" id="installation-instructions"> 432<div class="section">
191<h2><a class="toc-backref" href="#id14" name="installation-instructions">Installation Instructions</a></h2> 433<h2><a class="toc-backref" href="#id14" id="installation-instructions" name="installation-instructions">Installation Instructions</a></h2>
192<p>The first real chapter (after some introduction) would be one about the Gentoo 434<p>The first real chapter (after some introduction) would be one about the Gentoo
193Installation. This chapter could then include all information regarding 435Installation. This chapter could then include all information regarding
194alternative installation instructions, architecture specific instructions, 436alternative installation instructions, architecture specific instructions,
195partitioning schemes, RAID installations and more without continuously 437partitioning schemes, RAID installations and more without continuously
196referring to other sections throughout the handbook.</p> 438referring to other sections throughout the handbook.</p>
197<p>In other words, a user that wants to install Gentoo Linux on his SPARC with 439<p>In other words, a user that wants to install Gentoo Linux on his SPARC with
198ATA RAID should be able to do so following the instructions in the chapter 440ATA RAID should be able to do so following the instructions in the chapter
199<em>without</em> having to go forth and back between several pages. Creating such a 441<em>without</em> having to go forth and back between several pages. Creating such a
200chapter is not that easy just because we don't want our users to be sent from 442chapter is not that easy just because we don't want our users to be sent from
201left to right and over again.</p> 443left to right and over again.</p>
202<p>Developing this chapter should be done in parallel with the development of the 444<p>Developing this chapter should be done in parallel with the development of the
203current guides (who still have a higher priority since these are still the 445current guides (who still have a higher priority since these are still the
204official installation instructions as long as the chapter in the handbook 446official installation instructions as long as the chapter in the handbook
205isn't finished and reviewed for accuracy).</p> 447isn't finished and reviewed for accuracy).</p>
206</div> 448</div>
207<div class="section" id="system-administration"> 449<div class="section">
208<h2><a class="toc-backref" href="#id15" name="system-administration">System Administration</a></h2> 450<h2><a class="toc-backref" href="#id15" id="system-administration" name="system-administration">System Administration</a></h2>
209<p>This chapter, which bases its content on an existing base installation of 451<p>This chapter, which bases its content on an existing base installation of
210Gentoo, described in the previous chapter, contains sections for several 452Gentoo, described in the previous chapter, contains sections for several
211important administration items. This is a chapter that currently doesn't have 453important administration items. This is a chapter that currently doesn't have
212many affected guides, but is very important to make Gentoo work (and be 454many affected guides, but is very important to make Gentoo work (and be
213documented) in server-environments.</p> 455documented) in server-environments.</p>
228- Security 470- Security
229 471
230- Clustering 472- Clustering
231</pre> 473</pre>
232</div> 474</div>
233<div class="section" id="gentoo-development"> 475<div class="section">
234<h2><a class="toc-backref" href="#id16" name="gentoo-development">Gentoo Development</a></h2> 476<h2><a class="toc-backref" href="#id16" id="gentoo-development" name="gentoo-development">Gentoo Development</a></h2>
235<p>As previously explained, this chapter would contain all the information needed 477<p>As previously explained, this chapter would contain all the information needed
236to help the Gentoo development. It would embrace all the current existing 478to help the Gentoo development. It would embrace all the current existing
237guides regarding Ebuild and Eclass development, Stage Creation, Gentoo Policy 479guides regarding Ebuild and Eclass development, Stage Creation, Gentoo Policy
238etc.</p> 480etc.</p>
239</div> 481</div>
240<div class="section" id="user-applications"> 482<div class="section">
241<h2><a class="toc-backref" href="#id17" name="user-applications">User Applications</a></h2> 483<h2><a class="toc-backref" href="#id17" id="user-applications" name="user-applications">User Applications</a></h2>
242<p>Whereas the System Administration chapter contains the information on how to 484<p>Whereas the System Administration chapter contains the information on how to
243install software and services (such as XFree), this chapter would contain 485install software and services (such as XFree), this chapter would contain
244information for the users (not the administrators) on how they can use 486information for the users (not the administrators) on how they can use
245software installed by the system administrator.</p> 487software installed by the system administrator.</p>
246<p>Gentoo currently has several guides that describe such user applications 488<p>Gentoo currently has several guides that describe such user applications
248appreciate, so neglecting them would be signing our own death wish :)</p> 490appreciate, so neglecting them would be signing our own death wish :)</p>
249<p>Due to the nature of these documents, the User Applications chapter will exist 491<p>Due to the nature of these documents, the User Applications chapter will exist
250of independent sections.</p> 492of independent sections.</p>
251</div> 493</div>
252</div> 494</div>
253<div class="section" id="backwards-compatibility"> 495<div class="section">
254<h1><a class="toc-backref" href="#id18" name="backwards-compatibility">Backwards Compatibility</a></h1> 496<h1><a class="toc-backref" href="#id18" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
255<p>By making only small changes (actually extending) the GuideXML format, it is 497<p>By making only small changes (actually extending) the GuideXML format, it is
256possible (and even adviseable) to develop each chapter on its own parallel 498possible (and even adviseable) to develop each chapter on its own parallel
257with the guides that are involved.</p> 499with the guides that are involved.</p>
258<p>By developing the handbook in a subdirectory of the current documentation 500<p>By developing the handbook in a subdirectory of the current documentation
259directory (for instance <tt class="literal"><span class="pre">http://www.gentoo.org/doc/en/handbook</span></tt>) we maintain 501directory (for instance <tt class="docutils literal"><span class="pre">http://www.gentoo.org/doc/en/handbook</span></tt>) we maintain
260the current documentation. When a chapter on the handbook is finished, the 502the current documentation. When a chapter on the handbook is finished, the
261involved documents can contain a big note on top, declaring that they are now 503involved documents can contain a big note on top, declaring that they are now
262obsoleted by the handbook's chapter.</p> 504obsoleted by the handbook's chapter.</p>
263<p>However, note that this handbook does <strong>not</strong> and will <strong>not</strong> embrace all 505<p>However, note that this handbook does <strong>not</strong> and will <strong>not</strong> embrace all
264documents that the Gentoo Documentation Project produces. It is very likely 506documents that the Gentoo Documentation Project produces. It is very likely
265that there are guides that don't have a clear position inside this handbook. 507that there are guides that don't have a clear position inside this handbook.
266Instead of forcing the guide somewhere, we should leave the guide as a 508Instead of forcing the guide somewhere, we should leave the guide as a
267stand-alone document.</p> 509stand-alone document.</p>
268</div> 510</div>
269<div class="section" id="reference-implementation"> 511<div class="section">
270<h1><a class="toc-backref" href="#id19" name="reference-implementation">Reference Implementation</a></h1> 512<h1><a class="toc-backref" href="#id19" id="reference-implementation" name="reference-implementation">Reference Implementation</a></h1>
271<p>This is a possible roadmap for the Gentoo Handbook:</p> 513<p>This is a possible roadmap for the Gentoo Handbook:</p>
272<pre class="literal-block"> 514<pre class="literal-block">
273- Improve the GuideXML format, possibly creating a handbook.xsl stylesheet 515- Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
274(and leave the guide.xsl as it is now). 516(and leave the guide.xsl as it is now).
275 517
276- Implement the Installation Instructions 518- Implement the Installation Instructions
277 519
278- Develop a consistent layout, keeping the guides that are to be implemented 520- Develop a consistent layout, keeping the guides that are to be implemented
279 in mind. 521 in mind.
280 522
281- Include all referenced guides. Do *not* extend it yet. 523- Include all referenced guides. Do *not* extend it yet.
282 524
283- Review the installation instructions and make them official 525- Review the installation instructions and make them official
289- Implement the User Application Instructions 531- Implement the User Application Instructions
290 532
291- Implement the System Administration Instructions 533- Implement the System Administration Instructions
292</pre> 534</pre>
293</div> 535</div>
294<div class="section" id="references"> 536<div class="section">
295<h1><a class="toc-backref" href="#id20" name="references">References</a></h1> 537<h1><a class="toc-backref" href="#id20" id="references" name="references">References</a></h1>
296<table class="footnote" frame="void" id="instguide" rules="none"> 538<table class="docutils footnote" frame="void" id="instguide" rules="none">
297<colgroup><col class="label" /><col /></colgroup> 539<colgroup><col class="label" /><col /></colgroup>
298<tbody valign="top"> 540<tbody valign="top">
299<tr><td class="label"><a class="fn-backref" href="#id1" name="instguide">[1]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/gentoo-x86-install.xml">http://www.gentoo.org/doc/en/gentoo-x86-install.xml</a></td></tr> 541<tr><td class="label"><a class="fn-backref" href="#id1" name="instguide">[1]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/gentoo-x86-install.xml">http://www.gentoo.org/doc/en/gentoo-x86-install.xml</a></td></tr>
300</tbody> 542</tbody>
301</table> 543</table>
302<table class="footnote" frame="void" id="altinst" rules="none"> 544<table class="docutils footnote" frame="void" id="altinst" rules="none">
303<colgroup><col class="label" /><col /></colgroup> 545<colgroup><col class="label" /><col /></colgroup>
304<tbody valign="top"> 546<tbody valign="top">
305<tr><td class="label"><a class="fn-backref" href="#id2" name="altinst">[2]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/altinstall.xml">http://www.gentoo.org/doc/en/altinstall.xml</a></td></tr> 547<tr><td class="label"><a class="fn-backref" href="#id2" name="altinst">[2]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/altinstall.xml">http://www.gentoo.org/doc/en/altinstall.xml</a></td></tr>
306</tbody> 548</tbody>
307</table> 549</table>
308<table class="footnote" frame="void" id="lvm" rules="none"> 550<table class="docutils footnote" frame="void" id="lvm" rules="none">
309<colgroup><col class="label" /><col /></colgroup> 551<colgroup><col class="label" /><col /></colgroup>
310<tbody valign="top"> 552<tbody valign="top">
311<tr><td class="label"><a class="fn-backref" href="#id3" name="lvm">[3]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/lvm.xml">http://www.gentoo.org/doc/en/lvm.xml</a></td></tr> 553<tr><td class="label"><a class="fn-backref" href="#id3" name="lvm">[3]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/lvm.xml">http://www.gentoo.org/doc/en/lvm.xml</a></td></tr>
312</tbody> 554</tbody>
313</table> 555</table>
314<table class="footnote" frame="void" id="fbsdhandbook" rules="none"> 556<table class="docutils footnote" frame="void" id="fbsdhandbook" rules="none">
315<colgroup><col class="label" /><col /></colgroup> 557<colgroup><col class="label" /><col /></colgroup>
316<tbody valign="top"> 558<tbody valign="top">
317<tr><td class="label"><a class="fn-backref" href="#id4" name="fbsdhandbook">[4]</a></td><td><a class="reference" href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html">http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html</a></td></tr> 559<tr><td class="label"><a class="fn-backref" href="#id4" name="fbsdhandbook">[4]</a></td><td><a class="reference" href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html">http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html</a></td></tr>
318</tbody> 560</tbody>
319</table> 561</table>
320<table class="footnote" frame="void" id="gdp" rules="none"> 562<table class="docutils footnote" frame="void" id="gdp" rules="none">
321<colgroup><col class="label" /><col /></colgroup> 563<colgroup><col class="label" /><col /></colgroup>
322<tbody valign="top"> 564<tbody valign="top">
323<tr><td class="label"><a class="fn-backref" href="#id5" name="gdp">[5]</a></td><td><a class="reference" href="http://www.gentoo.org/proj/en/gdp">http://www.gentoo.org/proj/en/gdp</a></td></tr> 565<tr><td class="label"><a class="fn-backref" href="#id5" name="gdp">[5]</a></td><td><a class="reference" href="http://www.gentoo.org/proj/en/gdp">http://www.gentoo.org/proj/en/gdp</a></td></tr>
324</tbody> 566</tbody>
325</table> 567</table>
326<table class="footnote" frame="void" id="guidexml" rules="none"> 568<table class="docutils footnote" frame="void" id="guidexml" rules="none">
327<colgroup><col class="label" /><col /></colgroup> 569<colgroup><col class="label" /><col /></colgroup>
328<tbody valign="top"> 570<tbody valign="top">
329<tr><td class="label"><a class="fn-backref" href="#id6" name="guidexml">[6]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/xml-guide.xml">http://www.gentoo.org/doc/en/xml-guide.xml</a></td></tr> 571<tr><td class="label"><a class="fn-backref" href="#id6" name="guidexml">[6]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/xml-guide.xml">http://www.gentoo.org/doc/en/xml-guide.xml</a></td></tr>
330</tbody> 572</tbody>
331</table> 573</table>
332<table class="footnote" frame="void" id="desktop" rules="none"> 574<table class="docutils footnote" frame="void" id="desktop" rules="none">
333<colgroup><col class="label" /><col /></colgroup> 575<colgroup><col class="label" /><col /></colgroup>
334<tbody valign="top"> 576<tbody valign="top">
335<tr><td class="label"><a class="fn-backref" href="#id7" name="desktop">[7]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/desktop.xml">http://www.gentoo.org/doc/en/desktop.xml</a></td></tr> 577<tr><td class="label"><a class="fn-backref" href="#id7" name="desktop">[7]</a></td><td><a class="reference" href="http://www.gentoo.org/doc/en/desktop.xml">http://www.gentoo.org/doc/en/desktop.xml</a></td></tr>
336</tbody> 578</tbody>
337</table> 579</table>
338<table class="footnote" frame="void" id="gendoc" rules="none"> 580<table class="docutils footnote" frame="void" id="gendoc" rules="none">
339<colgroup><col class="label" /><col /></colgroup> 581<colgroup><col class="label" /><col /></colgroup>
340<tbody valign="top"> 582<tbody valign="top">
341<tr><td class="label"><a class="fn-backref" href="#id8" name="gendoc">[8]</a></td><td><a class="reference" href="http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5">http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5</a></td></tr> 583<tr><td class="label"><a class="fn-backref" href="#id8" name="gendoc">[8]</a></td><td><a class="reference" href="http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5">http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5</a></td></tr>
342</tbody> 584</tbody>
343</table> 585</table>
344</div> 586</div>
345<div class="section" id="copyright"> 587<div class="section">
346<h1><a class="toc-backref" href="#id21" name="copyright">Copyright</a></h1> 588<h1><a class="toc-backref" href="#id21" id="copyright" name="copyright">Copyright</a></h1>
347<p>This document has been placed in the public domain.</p> 589<p>This document has been placed in the public domain.</p>
348</div> 590</div>
349</div>
350 591
351<hr class="footer"/> 592</div>
352<div class="footer"> 593<div class="footer">
594<hr class="footer" />
353<a class="reference" href="glep-0013.txt">View document source</a>. 595<a class="reference" href="glep-0013.txt">View document source</a>.
354Generated on: 2003-08-20 02:26 UTC. 596Generated on: 2006-10-10 20:23 UTC.
355Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. 597Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
598
356</div> 599</div>
357</body> 600</body>
358</html> 601</html>
359 602

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20