diff options
Diffstat (limited to 'glep-0013.rst')
| -rw-r--r-- | glep-0013.rst | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/glep-0013.rst b/glep-0013.rst new file mode 100644 index 0000000..2542736 --- /dev/null +++ b/glep-0013.rst @@ -0,0 +1,286 @@ +GLEP: 13 +Title: Providing the users with a Gentoo Handbook +Version: $Revision$ +Last-Modified: $Date$ +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 of course 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 Alternative 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 of course the guide ends with ``</guide>``. +The ``<chapter>`` tag divides the document into separate 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. Referring 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 advisable) 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 work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +Unported License. To view a copy of this license, visit +http://creativecommons.org/licenses/by-sa/3.0/. |