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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (hide annotations) (download) (as text)
Mon Oct 25 17:05:50 2004 UTC (14 years, 2 months ago) by g2boojum
Branch: MAIN
Changes since 1.1: +9 -9 lines
File MIME type: text/html

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

  ViewVC Help
Powered by ViewVC 1.1.20