| Title: | Providing the users with a Gentoo Handbook |
|---|---|
| Version: | 1.1 | +
| Version: | 1.2 |
| Last-Modified: | 2003/08/20 02:28:47 | +
| Last-Modified: | 2004/10/26 00:21:28 |
| Author: | Sven Vermeulen <swift at gentoo.org> |
| Type: | Standards Track |
| Content-Type: | text/x-rst | +
| Content-Type: | text/x-rst |
| Created: | 15 Aug 2003 |
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, +every aspect of the Gentoo distribution: installation, administration, application usage, development etc.
Gentoo's current Installation Guide [1] 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, @@ -94,8 +336,8 @@ 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 :)
To address the beforementioned problem, there are two ideas:
To implement such a handbook, the Gentoo Documentation Project [5] needs a -rewritten stylesheet for its GuideXML [6] 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 +rewritten stylesheet for its GuideXML [6] 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: @@ -128,14 +370,14 @@
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 +the Aternative Installation Guide, LVM Guide, Platform-specific Installation Guides, etc.
Other chapters that need to be put in place are:
The following sections describe these steps more in detail...
-The GuideXML format should be extended with the following items:
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.
+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.
+<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" />.
+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 +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.
+preferable: <chapter name="installation">, <section +name="partitioning"> etc. Refering would then be #installation and +#partitioning respectively.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, @@ -196,16 +438,16 @@ 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 +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).
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 @@ -230,15 +472,15 @@ - Clustering
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.
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 @@ -250,13 +492,13 @@ of independent sections.
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 +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.
@@ -266,8 +508,8 @@ Instead of forcing the guide somewhere, we should leave the guide as a stand-alone document.This is a possible roadmap for the Gentoo Handbook:
- Improve the GuideXML format, possibly creating a handbook.xsl stylesheet @@ -275,7 +517,7 @@ - Implement the Installation Instructions -- Develop a consistent layout, keeping the guides that are to be implemented +- Develop a consistent layout, keeping the guides that are to be implemented in mind. - Include all referenced guides. Do *not* extend it yet. @@ -291,68 +533,69 @@ - Implement the System Administration Instructions