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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (hide annotations) (download)
Tue Oct 26 00:21:28 2004 UTC (9 years, 8 months ago) by g2boojum
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +4 -4 lines
File MIME type: text/plain
fixes

1 g2boojum 1.1 GLEP: 13
2     Title: Providing the users with a Gentoo Handbook
3 g2boojum 1.2 Version: $Revision: 1.1 $
4     Last-Modified: $Date: 2003/08/20 02:28:47 $
5 g2boojum 1.1 Author: Sven Vermeulen <swift@gentoo.org>
6 g2boojum 1.2 Status: Final
7 g2boojum 1.1 Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 15 Aug 2003
10 g2boojum 1.2 Post-History: 19-Aug-2003 25-Oct-2004
11 g2boojum 1.1
12     Abstract
13     ========
14    
15     This GLEP provides a vision on the evolution of the Gentoo Documentation,
16     namely a handbook-like document that provides its readers documentation about
17     every aspect of the Gentoo distribution: installation, administration,
18     application usage, development etc.
19    
20     Motivation
21     ==========
22    
23     Gentoo's current Installation Guide [#InstGuide]_ is rapidly growing, being
24     extended with more and more features that the Gentoo users can help with their
25     quest for the perfect installation. This increase is needed and a Good Thing,
26     but it makes the guide less easy to read or use as reference.
27    
28     There is no reason whatsoever that this evolution will stagnate, on the
29     contrary: people start asking why the Alternative Installation Guide
30     [#AltInst]_ isn't merged into the Gentoo Installation Guide, or why the
31     platform-specific installation guides can't be merged as they all use the same
32     steps (with a few differences). I myself even hope to merge our LVM Guide
33     [#LVM]_ into the Installation Guide as I believe several of our users would
34     love to use LVM on their machines, but currently don't because they don't know
35     how handy and easy it is -- you all know this feeling :)
36    
37     Rationale
38     =========
39    
40     To address the beforementioned problem, there are two ideas:
41    
42     - Split the Installation Guide into several independent guides. For instance,
43     we can move the information regarding the kernelconfiguration into the
44     Kernel Guide, create a partitioning-howto that decribes the fdisk (and
45     possibly others) steps users need to go through, etc.
46    
47     - Merge all information into one Big Handbook. This is ofcourse an idea that
48     we borrow from our FreeBSD friends [#FBSDHandBook]_ who already have an
49     extensive handbook related to their BSD-distribution.
50    
51     It is this second idea that this GLEP describes.
52    
53     This handbook-idea doesn't decrease the installation instructions, on the
54     contrary, it extends them. However, by choosing a multiple-page handbook-like
55     document, our users receive a fully integrated document that embraces
56     everything he or she wants to know. It will also make it more easy to provide
57     printable documentation (in PDF or other form) without loosing the comfort of
58     having the installation documents online and on the LiveCDs.
59    
60     Implementation
61     ==============
62    
63     To implement such a handbook, the Gentoo Documentation Project [#GDP]_ needs a
64     rewritten stylesheet for its GuideXML [#GuideXML]_ format. Since there are no
65     problems with GuideXML itself, and since it is very flexible in its use, the
66     recommendation to stick with GuideXML is clear. We do need some extra features
67     in GuideXML, without breaking the current GuideXML implementation.
68    
69     This last thing is important, since implementing this handbook-like document
70     should be done parallel to the development of our current documentation:
71     developing the Gentoo Handbook takes a long time and we don't want to force
72     our users to use a non-usable document.
73    
74     After improving the GuideXML format, the first things that need to be
75     addressed are the installation instructions. They should be merged with other,
76     existing guides that inform the user with installation-specific items (such as
77     the Aternative Installation Guide, LVM Guide, Platform-specific Installation
78     Guides, etc.
79    
80     Other chapters that need to be put in place are:
81    
82     - A chapter on Gentoo Development, which embraces all current
83     development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo
84     Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been
85     frequently asked by the Gentoo ebuild maintainers and several other Gentoo
86     Developers.
87    
88     - A chapter specific to System Administration, such as Mailserver
89     Administration, User Administration, Printing Administration etc. We already
90     have several guides that describe parts of these items.
91    
92     - A chapter specific to Gentoo Usage, including our popular Desktop
93     Configuration Guide [#Desktop]_ and several Application-specific guides.
94    
95     The following sections describe these steps more in detail...
96    
97     Extending GuideXML
98     ------------------
99    
100     The GuideXML format should be extended with the following items:
101    
102     - More depth regarding information-divisions.
103    
104     - "Including" external sourcecode
105    
106     - Easier in-document references
107    
108     Our current GuideXML format provides us the following depth regarding
109     information-division::
110    
111     <guide>
112     <chapter>
113     <section>
114    
115     The ``<guide>`` tag is currently a one-time tag: it defines the start of the
116     guide, and ofcourse the guide ends with ``</guide>``.
117     The ``<chapter>`` tag divides the document into seperate chapters. However,
118     most of our documents have small chapters, whereas normal books and documents
119     have chapters that encompasses several pages.
120     The ``<section>`` tag further divides the chapter in which it resides.
121    
122     This means that our current installation guides have a division-depth of 2:
123     you can define a chapter, and in that chapter make subdivisions with
124     ``<section>``. This is however insufficient for a handbook-like document. To
125     improve the GuideXML, we can add ``<subsection>`` and, if needed,
126     ``<subsubsection>``, based on LaTeX's divisions.
127    
128    
129     Another requisite is to be able to include external documents. Without this
130     possibility, maintaining the handbook would be cumbersome to say the least.
131     XSLT (which is used to process the GuideXML files) can easily provide this, so
132     there are no specific needs to include this feature.
133    
134     A possible tag would be ``<include file="foobar.xml" />``.
135    
136     With such a division, we could have each chapter inside its own document,
137     making maintenance far more easy.
138    
139    
140     The final implementation is in-document references. Currently, the Gentoo
141     Documentation Developers have so guess in what chapter a certain section
142     resides, and what section we are actually discussing: ``#doc_chap4_sect3``
143     provides us with a link to chapter 4, section 3. This is a workable
144     implementation for small documents, but impossible for handbooks.
145    
146     Implementing a more HTML-alike reference inside the division-tags would be
147     preferable: ``<chapter name="installation">``, ``<section
148     name="partitioning">`` etc. Refering would then be ``#installation`` and
149     ``#partitioning`` respectively.
150    
151    
152     Installation Instructions
153     -------------------------
154    
155     The first real chapter (after some introduction) would be one about the Gentoo
156     Installation. This chapter could then include all information regarding
157     alternative installation instructions, architecture specific instructions,
158     partitioning schemes, RAID installations and more without continuously
159     referring to other sections throughout the handbook.
160    
161     In other words, a user that wants to install Gentoo Linux on his SPARC with
162     ATA RAID should be able to do so following the instructions in the chapter
163     *without* having to go forth and back between several pages. Creating such a
164     chapter is not that easy just because we don't want our users to be sent from
165     left to right and over again.
166    
167     Developing this chapter should be done in parallel with the development of the
168     current guides (who still have a higher priority since these are still the
169     official installation instructions as long as the chapter in the handbook
170     isn't finished and reviewed for accuracy).
171    
172     System Administration
173     ---------------------
174    
175     This chapter, which bases its content on an existing base installation of
176     Gentoo, described in the previous chapter, contains sections for several
177     important administration items. This is a chapter that currently doesn't have
178     many affected guides, but is very important to make Gentoo work (and be
179     documented) in server-environments.
180    
181     The sections contain information on, but not limited to::
182    
183     - Software Administration
184    
185     - User Administration
186    
187     - Mail Administration
188    
189     - Print Services
190    
191     - Network Administration
192    
193     - Storage Management
194    
195     - Security
196    
197     - Clustering
198    
199    
200     Gentoo Development
201     ------------------
202    
203     As previously explained, this chapter would contain all the information needed
204     to help the Gentoo development. It would embrace all the current existing
205     guides regarding Ebuild and Eclass development, Stage Creation, Gentoo Policy
206     etc.
207    
208    
209     User Applications
210     -----------------
211    
212     Whereas the System Administration chapter contains the information on how to
213     install software and services (such as XFree), this chapter would contain
214     information for the users (not the administrators) on how they can use
215     software installed by the system administrator.
216    
217     Gentoo currently has several guides that describe such user applications
218     [#GenDoc]_ and it seems that these are guides that our users really
219     appreciate, so neglecting them would be signing our own death wish :)
220    
221     Due to the nature of these documents, the User Applications chapter will exist
222     of independent sections.
223    
224     Backwards Compatibility
225     =======================
226    
227     By making only small changes (actually extending) the GuideXML format, it is
228     possible (and even adviseable) to develop each chapter on its own parallel
229     with the guides that are involved.
230    
231     By developing the handbook in a subdirectory of the current documentation
232     directory (for instance ``http://www.gentoo.org/doc/en/handbook``) we maintain
233     the current documentation. When a chapter on the handbook is finished, the
234     involved documents can contain a big note on top, declaring that they are now
235     obsoleted by the handbook's chapter.
236    
237     However, note that this handbook does **not** and will **not** embrace all
238     documents that the Gentoo Documentation Project produces. It is very likely
239     that there are guides that don't have a clear position inside this handbook.
240     Instead of forcing the guide somewhere, we should leave the guide as a
241     stand-alone document.
242    
243     Reference Implementation
244     ========================
245    
246     This is a possible roadmap for the Gentoo Handbook::
247    
248     - Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
249     (and leave the guide.xsl as it is now).
250    
251     - Implement the Installation Instructions
252    
253     - Develop a consistent layout, keeping the guides that are to be implemented
254     in mind.
255    
256     - Include all referenced guides. Do *not* extend it yet.
257    
258     - Review the installation instructions and make them official
259    
260     - Extend at will :)
261    
262     - Implement the Gentoo Development Instructions
263    
264     - Implement the User Application Instructions
265    
266     - Implement the System Administration Instructions
267    
268    
269     References
270     ==========
271    
272     .. [#InstGuide] http://www.gentoo.org/doc/en/gentoo-x86-install.xml
273     .. [#AltInst] http://www.gentoo.org/doc/en/altinstall.xml
274     .. [#LVM] http://www.gentoo.org/doc/en/lvm.xml
275     .. [#FBSDHandBook] http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html
276     .. [#GDP] http://www.gentoo.org/proj/en/gdp
277     .. [#GuideXML] http://www.gentoo.org/doc/en/xml-guide.xml
278     .. [#Desktop] http://www.gentoo.org/doc/en/desktop.xml
279     .. [#GenDoc] http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5
280    
281     Copyright
282     =========
283    
284     This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20