1 |
GLEP: 13 |
2 |
Title: Providing the users with a Gentoo Handbook |
3 |
Version: $Revision: 1.1 $ |
4 |
Last-Modified: $Date: 2003/08/20 02:28:47 $ |
5 |
Author: Sven Vermeulen <swift@gentoo.org> |
6 |
Status: Final |
7 |
Type: Standards Track |
8 |
Content-Type: text/x-rst |
9 |
Created: 15 Aug 2003 |
10 |
Post-History: 19-Aug-2003 25-Oct-2004 |
11 |
|
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. |