en/glep/glep-0013.txt

GLEP: 13
Title: Providing the users with a Gentoo Handbook
Version: $Revision: 1.1 $
Last-Modified: $Date: 2003/08/20 02:28:47 $
Author: Sven Vermeulen <swift@gentoo.org>
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 15 Aug 2003
Post-History: 19-Aug-2003 25-Oct-2004

Abstract
========

This GLEP provides a vision on the evolution of the Gentoo Documentation,
namely a handbook-like document that provides its readers documentation about
every aspect of the Gentoo distribution: installation, administration, 
application usage, development etc.

Motivation
==========

Gentoo's current Installation Guide [#InstGuide]_ is rapidly growing, being
extended with more and more features that the Gentoo users can help with their
quest for the perfect installation. This increase is needed and a Good Thing,
but it makes the guide less easy to read or use as reference. 

There is no reason whatsoever that this evolution will stagnate, on the
contrary: people start asking why the Alternative Installation Guide
[#AltInst]_ isn't merged into the Gentoo Installation Guide, or why the
platform-specific installation guides can't be merged as they all use the same
steps (with a few differences). I myself even hope to merge our LVM Guide
[#LVM]_ into the Installation Guide as I believe several of our users would
love to use LVM on their machines, but currently don't because they don't know
how handy and easy it is -- you all know this feeling :)

Rationale
=========

To address the beforementioned problem, there are two ideas:

- Split the Installation Guide into several independent guides. For instance,
  we can move the information regarding the kernelconfiguration into the
  Kernel Guide, create a partitioning-howto that decribes the fdisk (and
  possibly others) steps users need to go through, etc.

- Merge all information into one Big Handbook. This is ofcourse an idea that
  we borrow from our FreeBSD friends [#FBSDHandBook]_ who already have an
  extensive handbook related to their BSD-distribution. 

It is this second idea that this GLEP describes.

This handbook-idea doesn't decrease the installation instructions, on the
contrary, it extends them. However, by choosing a multiple-page handbook-like
document, our users receive a fully integrated document that embraces
everything he or she wants to know. It will also make it more easy to provide
printable documentation (in PDF or other form) without loosing the comfort of
having the installation documents online and on the LiveCDs.

Implementation
==============

To implement such a handbook, the Gentoo Documentation Project [#GDP]_ needs a
rewritten stylesheet for its GuideXML [#GuideXML]_ format. Since there are no 
problems with GuideXML itself, and since it is very flexible in its use, the 
recommendation to stick with GuideXML is clear. We do need some extra features 
in GuideXML, without breaking the current GuideXML implementation.

This last thing is important, since implementing this handbook-like document
should be done parallel to the development of our current documentation:
developing the Gentoo Handbook takes a long time and we don't want to force
our users to use a non-usable document.

After improving the GuideXML format, the first things that need to be
addressed are the installation instructions. They should be merged with other,
existing guides that inform the user with installation-specific items (such as
the Aternative Installation Guide, LVM Guide, Platform-specific Installation 
Guides, etc.

Other chapters that need to be put in place are:

- A chapter on Gentoo Development, which embraces all current
  development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo 
  Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been 
  frequently asked by the Gentoo ebuild maintainers and several other Gentoo 
  Developers. 

- A chapter specific to System Administration, such as Mailserver
  Administration, User Administration, Printing Administration etc. We already
  have several guides that describe parts of these items. 

- A chapter specific to Gentoo Usage, including our popular Desktop
  Configuration Guide [#Desktop]_ and several Application-specific guides.

The following sections describe these steps more in detail...

Extending GuideXML
------------------

The GuideXML format should be extended with the following items:

- More depth regarding information-divisions.

- "Including" external sourcecode

- Easier in-document references

Our current GuideXML format provides us the following depth regarding
information-division::

    <guide>
        <chapter>
            <section>

The ``<guide>`` tag is currently a one-time tag: it defines the start of the
guide, and ofcourse the guide ends with ``</guide>``. 
The ``<chapter>`` tag divides the document into seperate chapters. However, 
most of our documents have small chapters, whereas normal books and documents 
have chapters that encompasses several pages. 
The ``<section>`` tag further divides the chapter in which it resides.

This means that our current installation guides have a division-depth of 2:
you can define a chapter, and in that chapter make subdivisions with
``<section>``. This is however insufficient for a handbook-like document. To
improve the GuideXML, we can add ``<subsection>`` and, if needed,
``<subsubsection>``, based on LaTeX's divisions.


Another requisite is to be able to include external documents. Without this
possibility, maintaining the handbook would be cumbersome to say the least.
XSLT (which is used to process the GuideXML files) can easily provide this, so
there are no specific needs to include this feature.

A possible tag would be ``<include file="foobar.xml" />``.

With such a division, we could have each chapter inside its own document,
making maintenance far more easy.


The final implementation is in-document references. Currently, the Gentoo
Documentation Developers have so guess in what chapter a certain section
resides, and what section we are actually discussing: ``#doc_chap4_sect3``
provides us with a link to chapter 4, section 3. This is a workable
implementation for small documents, but impossible for handbooks. 

Implementing a more HTML-alike reference inside the division-tags would be
preferable: ``<chapter name="installation">``, ``<section
name="partitioning">`` etc. Refering would then be ``#installation`` and
``#partitioning`` respectively.


Installation Instructions
-------------------------

The first real chapter (after some introduction) would be one about the Gentoo
Installation. This chapter could then include all information regarding
alternative installation instructions, architecture specific instructions,
partitioning schemes, RAID installations and more without continuously
referring to other sections throughout the handbook.

In other words, a user that wants to install Gentoo Linux on his SPARC with
ATA RAID should be able to do so following the instructions in the chapter
*without* having to go forth and back between several pages. Creating such a 
chapter is not that easy just because we don't want our users to be sent from 
left to right and over again.

Developing this chapter should be done in parallel with the development of the
current guides (who still have a higher priority since these are still the
official installation instructions as long as the chapter in the handbook
isn't finished and reviewed for accuracy). 

System Administration
---------------------

This chapter, which bases its content on an existing base installation of
Gentoo, described in the previous chapter, contains sections for several
important administration items. This is a chapter that currently doesn't have
many affected guides, but is very important to make Gentoo work (and be
documented) in server-environments.

The sections contain information on, but not limited to::

        - Software Administration

        - User Administration

        - Mail Administration

        - Print Services

        - Network Administration

        - Storage Management

        - Security

        - Clustering


Gentoo Development
------------------

As previously explained, this chapter would contain all the information needed
to help the Gentoo development. It would embrace all the current existing
guides regarding Ebuild and Eclass development, Stage Creation, Gentoo Policy
etc.


User Applications
-----------------

Whereas the System Administration chapter contains the information on how to
install software and services (such as XFree), this chapter would contain
information for the users (not the administrators) on how they can use
software installed by the system administrator.

Gentoo currently has several guides that describe such user applications
[#GenDoc]_ and it seems that these are guides that our users really
appreciate, so neglecting them would be signing our own death wish :)

Due to the nature of these documents, the User Applications chapter will exist
of independent sections.

Backwards Compatibility
=======================

By making only small changes (actually extending) the GuideXML format, it is
possible (and even adviseable) to develop each chapter on its own parallel
with the guides that are involved. 

By developing the handbook in a subdirectory of the current documentation
directory (for instance ``http://www.gentoo.org/doc/en/handbook``) we maintain
the current documentation. When a chapter on the handbook is finished, the
involved documents can contain a big note on top, declaring that they are now
obsoleted by the handbook's chapter.

However, note that this handbook does **not** and will **not** embrace all
documents that the Gentoo Documentation Project produces. It is very likely
that there are guides that don't have a clear position inside this handbook.
Instead of forcing the guide somewhere, we should leave the guide as a
stand-alone document.

Reference Implementation
========================

This is a possible roadmap for the Gentoo Handbook::

  - Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
  (and leave the guide.xsl as it is now).

  - Implement the Installation Instructions

  - Develop a consistent layout, keeping the guides that are to be implemented 
    in mind.

  - Include all referenced guides. Do *not* extend it yet.

  - Review the installation instructions and make them official

  - Extend at will :)

  - Implement the Gentoo Development Instructions

  - Implement the User Application Instructions

  - Implement the System Administration Instructions


References
==========

.. [#InstGuide] http://www.gentoo.org/doc/en/gentoo-x86-install.xml
.. [#AltInst] http://www.gentoo.org/doc/en/altinstall.xml
.. [#LVM] http://www.gentoo.org/doc/en/lvm.xml
.. [#FBSDHandBook] http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html
.. [#GDP] http://www.gentoo.org/proj/en/gdp
.. [#GuideXML] http://www.gentoo.org/doc/en/xml-guide.xml
.. [#Desktop] http://www.gentoo.org/doc/en/desktop.xml
.. [#GenDoc] http://www.gentoo.org/main/en/docs.xml#doc_chap1_sect5

Copyright
=========

This document has been placed in the public domain.
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.