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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (hide annotations) (download) (as text)
Sun Oct 14 17:00:15 2007 UTC (6 years, 11 months ago) by antarus
Branch: MAIN
CVS Tags: HEAD
Changes since 1.4: +4 -251 lines
File MIME type: text/html
the canary on 53 went well, changing the rest

1 g2boojum 1.1 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 antarus 1.5
5 g2boojum 1.1 <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 g2boojum 1.3 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8 g2boojum 1.1 <title>GLEP 13 -- Providing the users with a Gentoo Handbook</title>
9 antarus 1.5 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10 g2boojum 1.1 </head>
11     <body bgcolor="white">
12     <table class="navigation" cellpadding="0" cellspacing="0"
13     width="100%" border="0">
14     <tr><td class="navicon" width="150" height="35">
15     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17     border="0" width="150" height="35" /></a></td>
18     <td class="textlinks" align="left">
19     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20 antarus 1.5 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 g2boojum 1.3 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0013.txt">GLEP Source</a></b>]
22 g2boojum 1.1 </td></tr></table>
23 g2boojum 1.3 <table class="rfc2822 docutils field-list" frame="void" rules="none">
24 g2boojum 1.1 <col class="field-name" />
25     <col class="field-body" />
26     <tbody valign="top">
27     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">13</td>
28     </tr>
29     <tr class="field"><th class="field-name">Title:</th><td class="field-body">Providing the users with a Gentoo Handbook</td>
30     </tr>
31 g2boojum 1.3 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
32 g2boojum 1.1 </tr>
33 g2boojum 1.3 <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>
34 g2boojum 1.1 </tr>
35     <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>
36     </tr>
37 g2boojum 1.2 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
38 g2boojum 1.1 </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </tr>
41 g2boojum 1.3 <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>
42 g2boojum 1.1 </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">15 Aug 2003</td>
44     </tr>
45 g2boojum 1.2 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">19-Aug-2003 25-Oct-2004</td>
46 g2boojum 1.1 </tr>
47     </tbody>
48     </table>
49     <hr />
50 g2boojum 1.3 <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52 g2boojum 1.1 <ul class="simple">
53     <li><a class="reference" href="#abstract" id="id9" name="id9">Abstract</a></li>
54     <li><a class="reference" href="#motivation" id="id10" name="id10">Motivation</a></li>
55     <li><a class="reference" href="#rationale" id="id11" name="id11">Rationale</a></li>
56     <li><a class="reference" href="#implementation" id="id12" name="id12">Implementation</a><ul>
57     <li><a class="reference" href="#extending-guidexml" id="id13" name="id13">Extending GuideXML</a></li>
58     <li><a class="reference" href="#installation-instructions" id="id14" name="id14">Installation Instructions</a></li>
59     <li><a class="reference" href="#system-administration" id="id15" name="id15">System Administration</a></li>
60     <li><a class="reference" href="#gentoo-development" id="id16" name="id16">Gentoo Development</a></li>
61     <li><a class="reference" href="#user-applications" id="id17" name="id17">User Applications</a></li>
62     </ul>
63     </li>
64     <li><a class="reference" href="#backwards-compatibility" id="id18" name="id18">Backwards Compatibility</a></li>
65     <li><a class="reference" href="#reference-implementation" id="id19" name="id19">Reference Implementation</a></li>
66     <li><a class="reference" href="#references" id="id20" name="id20">References</a></li>
67     <li><a class="reference" href="#copyright" id="id21" name="id21">Copyright</a></li>
68     </ul>
69     </div>
70 g2boojum 1.3 <div class="section">
71     <h1><a class="toc-backref" href="#id9" id="abstract" name="abstract">Abstract</a></h1>
72 g2boojum 1.1 <p>This GLEP provides a vision on the evolution of the Gentoo Documentation,
73     namely a handbook-like document that provides its readers documentation about
74 g2boojum 1.3 every aspect of the Gentoo distribution: installation, administration,
75 g2boojum 1.1 application usage, development etc.</p>
76     </div>
77 g2boojum 1.3 <div class="section">
78     <h1><a class="toc-backref" href="#id10" id="motivation" name="motivation">Motivation</a></h1>
79 g2boojum 1.1 <p>Gentoo's current Installation Guide <a class="footnote-reference" href="#instguide" id="id1" name="id1">[1]</a> is rapidly growing, being
80     extended with more and more features that the Gentoo users can help with their
81     quest for the perfect installation. This increase is needed and a Good Thing,
82     but it makes the guide less easy to read or use as reference.</p>
83     <p>There is no reason whatsoever that this evolution will stagnate, on the
84     contrary: people start asking why the Alternative Installation Guide
85     <a class="footnote-reference" href="#altinst" id="id2" name="id2">[2]</a> isn't merged into the Gentoo Installation Guide, or why the
86     platform-specific installation guides can't be merged as they all use the same
87     steps (with a few differences). I myself even hope to merge our LVM Guide
88     <a class="footnote-reference" href="#lvm" id="id3" name="id3">[3]</a> into the Installation Guide as I believe several of our users would
89     love to use LVM on their machines, but currently don't because they don't know
90     how handy and easy it is -- you all know this feeling :)</p>
91     </div>
92 g2boojum 1.3 <div class="section">
93     <h1><a class="toc-backref" href="#id11" id="rationale" name="rationale">Rationale</a></h1>
94 g2boojum 1.1 <p>To address the beforementioned problem, there are two ideas:</p>
95     <ul class="simple">
96     <li>Split the Installation Guide into several independent guides. For instance,
97     we can move the information regarding the kernelconfiguration into the
98     Kernel Guide, create a partitioning-howto that decribes the fdisk (and
99     possibly others) steps users need to go through, etc.</li>
100     <li>Merge all information into one Big Handbook. This is ofcourse an idea that
101     we borrow from our FreeBSD friends <a class="footnote-reference" href="#fbsdhandbook" id="id4" name="id4">[4]</a> who already have an
102     extensive handbook related to their BSD-distribution.</li>
103     </ul>
104     <p>It is this second idea that this GLEP describes.</p>
105     <p>This handbook-idea doesn't decrease the installation instructions, on the
106     contrary, it extends them. However, by choosing a multiple-page handbook-like
107     document, our users receive a fully integrated document that embraces
108     everything he or she wants to know. It will also make it more easy to provide
109     printable documentation (in PDF or other form) without loosing the comfort of
110     having the installation documents online and on the LiveCDs.</p>
111     </div>
112 g2boojum 1.3 <div class="section">
113     <h1><a class="toc-backref" href="#id12" id="implementation" name="implementation">Implementation</a></h1>
114 g2boojum 1.1 <p>To implement such a handbook, the Gentoo Documentation Project <a class="footnote-reference" href="#gdp" id="id5" name="id5">[5]</a> needs a
115 g2boojum 1.3 rewritten stylesheet for its GuideXML <a class="footnote-reference" href="#guidexml" id="id6" name="id6">[6]</a> format. Since there are no
116     problems with GuideXML itself, and since it is very flexible in its use, the
117     recommendation to stick with GuideXML is clear. We do need some extra features
118 g2boojum 1.1 in GuideXML, without breaking the current GuideXML implementation.</p>
119     <p>This last thing is important, since implementing this handbook-like document
120     should be done parallel to the development of our current documentation:
121     developing the Gentoo Handbook takes a long time and we don't want to force
122     our users to use a non-usable document.</p>
123     <p>After improving the GuideXML format, the first things that need to be
124     addressed are the installation instructions. They should be merged with other,
125     existing guides that inform the user with installation-specific items (such as
126 g2boojum 1.3 the Aternative Installation Guide, LVM Guide, Platform-specific Installation
127 g2boojum 1.1 Guides, etc.</p>
128     <p>Other chapters that need to be put in place are:</p>
129     <ul class="simple">
130     <li>A chapter on Gentoo Development, which embraces all current
131 g2boojum 1.3 development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo
132     Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been
133     frequently asked by the Gentoo ebuild maintainers and several other Gentoo
134 g2boojum 1.1 Developers.</li>
135     <li>A chapter specific to System Administration, such as Mailserver
136     Administration, User Administration, Printing Administration etc. We already
137     have several guides that describe parts of these items.</li>
138     <li>A chapter specific to Gentoo Usage, including our popular Desktop
139     Configuration Guide <a class="footnote-reference" href="#desktop" id="id7" name="id7">[7]</a> and several Application-specific guides.</li>
140     </ul>
141     <p>The following sections describe these steps more in detail...</p>
142 g2boojum 1.3 <div class="section">
143     <h2><a class="toc-backref" href="#id13" id="extending-guidexml" name="extending-guidexml">Extending GuideXML</a></h2>
144 g2boojum 1.1 <p>The GuideXML format should be extended with the following items:</p>
145     <ul class="simple">
146     <li>More depth regarding information-divisions.</li>
147     <li>&quot;Including&quot; external sourcecode</li>
148     <li>Easier in-document references</li>
149     </ul>
150     <p>Our current GuideXML format provides us the following depth regarding
151     information-division:</p>
152     <pre class="literal-block">
153     &lt;guide&gt;
154     &lt;chapter&gt;
155     &lt;section&gt;
156     </pre>
157 g2boojum 1.3 <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
158     guide, and ofcourse the guide ends with <tt class="docutils literal"><span class="pre">&lt;/guide&gt;</span></tt>.
159     The <tt class="docutils literal"><span class="pre">&lt;chapter&gt;</span></tt> tag divides the document into seperate chapters. However,
160     most of our documents have small chapters, whereas normal books and documents
161     have chapters that encompasses several pages.
162     The <tt class="docutils literal"><span class="pre">&lt;section&gt;</span></tt> tag further divides the chapter in which it resides.</p>
163 g2boojum 1.1 <p>This means that our current installation guides have a division-depth of 2:
164     you can define a chapter, and in that chapter make subdivisions with
165 g2boojum 1.3 <tt class="docutils literal"><span class="pre">&lt;section&gt;</span></tt>. This is however insufficient for a handbook-like document. To
166     improve the GuideXML, we can add <tt class="docutils literal"><span class="pre">&lt;subsection&gt;</span></tt> and, if needed,
167     <tt class="docutils literal"><span class="pre">&lt;subsubsection&gt;</span></tt>, based on LaTeX's divisions.</p>
168 g2boojum 1.1 <p>Another requisite is to be able to include external documents. Without this
169     possibility, maintaining the handbook would be cumbersome to say the least.
170     XSLT (which is used to process the GuideXML files) can easily provide this, so
171     there are no specific needs to include this feature.</p>
172 g2boojum 1.3 <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>
173 g2boojum 1.1 <p>With such a division, we could have each chapter inside its own document,
174     making maintenance far more easy.</p>
175     <p>The final implementation is in-document references. Currently, the Gentoo
176     Documentation Developers have so guess in what chapter a certain section
177 g2boojum 1.3 resides, and what section we are actually discussing: <tt class="docutils literal"><span class="pre">#doc_chap4_sect3</span></tt>
178 g2boojum 1.1 provides us with a link to chapter 4, section 3. This is a workable
179     implementation for small documents, but impossible for handbooks.</p>
180     <p>Implementing a more HTML-alike reference inside the division-tags would be
181 g2boojum 1.3 preferable: <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>
182     <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
183     <tt class="docutils literal"><span class="pre">#partitioning</span></tt> respectively.</p>
184 g2boojum 1.1 </div>
185 g2boojum 1.3 <div class="section">
186     <h2><a class="toc-backref" href="#id14" id="installation-instructions" name="installation-instructions">Installation Instructions</a></h2>
187 g2boojum 1.1 <p>The first real chapter (after some introduction) would be one about the Gentoo
188     Installation. This chapter could then include all information regarding
189     alternative installation instructions, architecture specific instructions,
190     partitioning schemes, RAID installations and more without continuously
191     referring to other sections throughout the handbook.</p>
192     <p>In other words, a user that wants to install Gentoo Linux on his SPARC with
193     ATA RAID should be able to do so following the instructions in the chapter
194 g2boojum 1.3 <em>without</em> having to go forth and back between several pages. Creating such a
195     chapter is not that easy just because we don't want our users to be sent from
196 g2boojum 1.1 left to right and over again.</p>
197     <p>Developing this chapter should be done in parallel with the development of the
198     current guides (who still have a higher priority since these are still the
199     official installation instructions as long as the chapter in the handbook
200     isn't finished and reviewed for accuracy).</p>
201     </div>
202 g2boojum 1.3 <div class="section">
203     <h2><a class="toc-backref" href="#id15" id="system-administration" name="system-administration">System Administration</a></h2>
204 g2boojum 1.1 <p>This chapter, which bases its content on an existing base installation of
205     Gentoo, described in the previous chapter, contains sections for several
206     important administration items. This is a chapter that currently doesn't have
207     many affected guides, but is very important to make Gentoo work (and be
208     documented) in server-environments.</p>
209     <p>The sections contain information on, but not limited to:</p>
210     <pre class="literal-block">
211     - Software Administration
212    
213     - User Administration
214    
215     - Mail Administration
216    
217     - Print Services
218    
219     - Network Administration
220    
221     - Storage Management
222    
223     - Security
224    
225     - Clustering
226     </pre>
227     </div>
228 g2boojum 1.3 <div class="section">
229     <h2><a class="toc-backref" href="#id16" id="gentoo-development" name="gentoo-development">Gentoo Development</a></h2>
230 g2boojum 1.1 <p>As previously explained, this chapter would contain all the information needed
231     to help the Gentoo development. It would embrace all the current existing
232     guides regarding Ebuild and Eclass development, Stage Creation, Gentoo Policy
233     etc.</p>
234     </div>
235 g2boojum 1.3 <div class="section">
236     <h2><a class="toc-backref" href="#id17" id="user-applications" name="user-applications">User Applications</a></h2>
237 g2boojum 1.1 <p>Whereas the System Administration chapter contains the information on how to
238     install software and services (such as XFree), this chapter would contain
239     information for the users (not the administrators) on how they can use
240     software installed by the system administrator.</p>
241     <p>Gentoo currently has several guides that describe such user applications
242     <a class="footnote-reference" href="#gendoc" id="id8" name="id8">[8]</a> and it seems that these are guides that our users really
243     appreciate, so neglecting them would be signing our own death wish :)</p>
244     <p>Due to the nature of these documents, the User Applications chapter will exist
245     of independent sections.</p>
246     </div>
247     </div>
248 g2boojum 1.3 <div class="section">
249     <h1><a class="toc-backref" href="#id18" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
250 g2boojum 1.1 <p>By making only small changes (actually extending) the GuideXML format, it is
251     possible (and even adviseable) to develop each chapter on its own parallel
252     with the guides that are involved.</p>
253     <p>By developing the handbook in a subdirectory of the current documentation
254 g2boojum 1.3 directory (for instance <tt class="docutils literal"><span class="pre">http://www.gentoo.org/doc/en/handbook</span></tt>) we maintain
255 g2boojum 1.1 the current documentation. When a chapter on the handbook is finished, the
256     involved documents can contain a big note on top, declaring that they are now
257     obsoleted by the handbook's chapter.</p>
258     <p>However, note that this handbook does <strong>not</strong> and will <strong>not</strong> embrace all
259     documents that the Gentoo Documentation Project produces. It is very likely
260     that there are guides that don't have a clear position inside this handbook.
261     Instead of forcing the guide somewhere, we should leave the guide as a
262     stand-alone document.</p>
263     </div>
264 g2boojum 1.3 <div class="section">
265     <h1><a class="toc-backref" href="#id19" id="reference-implementation" name="reference-implementation">Reference Implementation</a></h1>
266 g2boojum 1.1 <p>This is a possible roadmap for the Gentoo Handbook:</p>
267     <pre class="literal-block">
268     - Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
269     (and leave the guide.xsl as it is now).
270    
271     - Implement the Installation Instructions
272    
273 g2boojum 1.3 - Develop a consistent layout, keeping the guides that are to be implemented
274 g2boojum 1.1 in mind.
275    
276     - Include all referenced guides. Do *not* extend it yet.
277    
278     - Review the installation instructions and make them official
279    
280     - Extend at will :)
281    
282     - Implement the Gentoo Development Instructions
283    
284     - Implement the User Application Instructions
285    
286     - Implement the System Administration Instructions
287     </pre>
288     </div>
289 g2boojum 1.3 <div class="section">
290     <h1><a class="toc-backref" href="#id20" id="references" name="references">References</a></h1>
291     <table class="docutils footnote" frame="void" id="instguide" rules="none">
292 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
293     <tbody valign="top">
294     <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>
295     </tbody>
296     </table>
297 g2boojum 1.3 <table class="docutils footnote" frame="void" id="altinst" rules="none">
298 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
299     <tbody valign="top">
300     <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>
301     </tbody>
302     </table>
303 g2boojum 1.3 <table class="docutils footnote" frame="void" id="lvm" rules="none">
304 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
305     <tbody valign="top">
306     <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>
307     </tbody>
308     </table>
309 g2boojum 1.3 <table class="docutils footnote" frame="void" id="fbsdhandbook" rules="none">
310 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
311     <tbody valign="top">
312     <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>
313     </tbody>
314     </table>
315 g2boojum 1.3 <table class="docutils footnote" frame="void" id="gdp" rules="none">
316 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
317     <tbody valign="top">
318     <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>
319     </tbody>
320     </table>
321 g2boojum 1.3 <table class="docutils footnote" frame="void" id="guidexml" rules="none">
322 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
323     <tbody valign="top">
324     <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>
325     </tbody>
326     </table>
327 g2boojum 1.3 <table class="docutils footnote" frame="void" id="desktop" rules="none">
328 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
329     <tbody valign="top">
330     <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>
331     </tbody>
332     </table>
333 g2boojum 1.3 <table class="docutils footnote" frame="void" id="gendoc" rules="none">
334 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
335     <tbody valign="top">
336     <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>
337     </tbody>
338     </table>
339     </div>
340 g2boojum 1.3 <div class="section">
341     <h1><a class="toc-backref" href="#id21" id="copyright" name="copyright">Copyright</a></h1>
342 g2boojum 1.1 <p>This document has been placed in the public domain.</p>
343     </div>
344 g2boojum 1.3
345 g2boojum 1.1 </div>
346 g2boojum 1.3 <div class="footer">
347 g2boojum 1.2 <hr class="footer" />
348 g2boojum 1.1 <a class="reference" href="glep-0013.txt">View document source</a>.
349 antarus 1.5 Generated on: 2007-10-13 13:39 UTC.
350 g2boojum 1.1 Generated 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.
351 g2boojum 1.3
352 g2boojum 1.1 </div>
353     </body>
354     </html>

  ViewVC Help
Powered by ViewVC 1.1.20