1 |
Hi, |
2 |
|
3 |
http://www.gentoo.org/proj/en/glep/glep-0013.html |
4 |
|
5 |
You all know that our current installation guide (more precisely, the x86 |
6 |
installation guide) is changing almost on a daily basis. It is also a very |
7 |
hot item in several discussions, because the LiveCDs are very hot. |
8 |
|
9 |
I have recently received a mail by drobbins to not have the installation |
10 |
guide grow even further, since it will become difficult to maintain, read and |
11 |
follow. And as you all know I'm not someone that shrugs and follows, so I |
12 |
decided to prepare a GLEP to be able for the installation guide to grow when |
13 |
it wants to ;) |
14 |
|
15 |
This GLEP talks about the creation of a Gentoo Handbook, akin to FreeBSD's |
16 |
handbook, starting with the chapter on installation. |
17 |
|
18 |
Now why a handbook, and what will we do about the ppl that say we copied that |
19 |
idea from FreeBSD? Well, with the latter, we just say "so?" because we know |
20 |
such a handbook is a frequently requested item, and it will make several of |
21 |
our -- currently independent -- guides more coherent. |
22 |
|
23 |
But the why's can be difficult. There is indeed another solution, splitting |
24 |
the installation guide into several smaller guides. The reason I opt for a |
25 |
handbook is because we can then enhance the installation instructions with |
26 |
more, integrated information. |
27 |
|
28 |
For instance, we can make the user choose LVM (something I know several of |
29 |
our users want, but didn't know it existed until after they installed |
30 |
Gentoo), and we can do it linearly, without forcing him to have two terminals |
31 |
open to see if he has encountered a "different" section, as is currently the |
32 |
case. |
33 |
|
34 |
We can also make the x86/PPC/SPARC/... installation instructions more |
35 |
integrated. Changes in Gentoo are felt all over the place. Currently, the x86 |
36 |
installation guide is the guide which is updated quickest. Other installation |
37 |
guides follow with some lag. By combining all instructions and have a clear |
38 |
way to denote x86-only, or ppc-only, or sparc-only sections, all |
39 |
architectures are treated equally. |
40 |
|
41 |
We also reduce the total amount of written documentation at first (later on, |
42 |
it'll grow as a natural evolution because of enhancements etc.) since double |
43 |
information is eliminated (if you read the ppc-installation guide for |
44 |
instance, you'll notice that most of it is the same for x86 and vice versa). |
45 |
|
46 |
Now I'm only ranting about the chapter regarding "Installing Gentoo" since, |
47 |
in the GLEP, this is the first chapter that should be worked on. Later, when |
48 |
that chapter is "finished" and official, the guide can and should be extended |
49 |
with other chapters, such as "System Administration", "Gentoo Development", |
50 |
"User Applications" and so on. |
51 |
|
52 |
To provide the Gentoo users with such a handbook, several steps need to be |
53 |
taken. First of all, a new stylesheet (with enhancements for the GuideXML |
54 |
format) should be written. This stylesheet should be able to support |
55 |
- multiple pages output |
56 |
- multiple pages input |
57 |
- deeper nesting of information blocks |
58 |
(chapter, section, subsection, subsubsection) |
59 |
- in-document references |
60 |
and, if possible, a way to convert it to a format that makes it easy to |
61 |
convert to, for instance, LaTeX or DocBook so books can be produced better. |
62 |
|
63 |
Such stylesheet-hocuspocus is not fantasy -- people with experience in XSL |
64 |
know this isn't too hard, but it requires a little time to produce such a |
65 |
stylesheet. In the mean time, development of the installation guide continues |
66 |
as it is now. |
67 |
|
68 |
When the stylesheet is finished, a first layout on the chapter should be |
69 |
written. This layout can be a listing of all sections, subsections and |
70 |
subsubsections and should list all guides that are being incorporated, |
71 |
e.g. |
72 |
- x86 installation guide |
73 |
- ppc installation guide |
74 |
- sparc installation guide |
75 |
- alternative installation guide |
76 |
- LVM guide |
77 |
- kernel guide |
78 |
- UML guide |
79 |
- ... |
80 |
|
81 |
Then the chapter can be incorporated. However, to make sure that this doesn't |
82 |
lead to spaghetti, we shouldn't add new items yet -- this is for when the |
83 |
chapter becomes official. This way we make sure that the "Installing Gentoo" |
84 |
chapter doesn't stay as an unofficial-work-in-progress. |
85 |
|
86 |
So, please read the GLEP and provide us with your comments! |
87 |
|
88 |
Wkr, |
89 |
Sven Vermeulen |
90 |
|
91 |
PS gentoo-dev ppl, please discuss this in gentoo-doc as this is purely |
92 |
documentation related. |
93 |
|
94 |
-- |
95 |
Save some animals, eat a vegetarian. |