Gentoo Archives: gentoo-dev

From: Sven Vermeulen <swift@g.o>
To: gentoo-doc@g.o
Cc: gentoo-dev@g.o
Subject: [gentoo-dev] GLEP 13 (brrrr) - Gentoo Handbook
Date: Wed, 20 Aug 2003 08:24:53
1 Hi,
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.
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 ;)
15 This GLEP talks about the creation of a Gentoo Handbook, akin to FreeBSD's
16 handbook, starting with the chapter on installation.
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.
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.
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.
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.
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).
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.
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.
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.
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 - ...
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.
86 So, please read the GLEP and provide us with your comments!
88 Wkr,
89 Sven Vermeulen
91 PS gentoo-dev ppl, please discuss this in gentoo-doc as this is purely
92 documentation related.
94 --
95 Save some animals, eat a vegetarian.