From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27331 invoked by uid 1002); 20 Aug 2003 08:24:53 -0000 Mailing-List: contact gentoo-dev-help@gentoo.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Received: (qmail 30959 invoked from network); 20 Aug 2003 08:24:53 -0000 Date: Wed, 20 Aug 2003 10:24:37 +0200 From: Sven Vermeulen To: gentoo-doc@gentoo.org Cc: gentoo-dev@gentoo.org Message-ID: <20030820082437.GE1138@gentoo.org> Reply-To: gentoo-doc@gentoo.org Mail-Followup-To: gentoo-doc@gentoo.org, gentoo-dev@gentoo.org Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="lteA1dqeVaWQ9QQl" Content-Disposition: inline X-Operating-System: Linux 2.4.20 X-Telephone: +32 486 460306 User-Agent: Mutt/1.5.4i Subject: [gentoo-dev] GLEP 13 (brrrr) - Gentoo Handbook X-Archives-Salt: 0572a835-8a19-49de-bb82-80871159b2fa X-Archives-Hash: f65e4c3ee4312addbab43263ac39d2cb --lteA1dqeVaWQ9QQl Content-Type: text/plain; charset=iso-8859-15 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Hi, http://www.gentoo.org/proj/en/glep/glep-0013.html You all know that our current installation guide (more precisely, the x86 installation guide) is changing almost on a daily basis. It is also a very hot item in several discussions, because the LiveCDs are very hot. I have recently received a mail by drobbins to not have the installation guide grow even further, since it will become difficult to maintain, read a= nd follow. And as you all know I'm not someone that shrugs and follows, so I decided to prepare a GLEP to be able for the installation guide to grow when it wants to ;)=20 This GLEP talks about the creation of a Gentoo Handbook, akin to FreeBSD's handbook, starting with the chapter on installation.=20 Now why a handbook, and what will we do about the ppl that say we copied th= at idea from FreeBSD? Well, with the latter, we just say "so?" because we know such a handbook is a frequently requested item, and it will make several of our -- currently independent -- guides more coherent. But the why's can be difficult. There is indeed another solution, splitting the installation guide into several smaller guides. The reason I opt for a handbook is because we can then enhance the installation instructions with more, integrated information. For instance, we can make the user choose LVM (something I know several of our users want, but didn't know it existed until after they installed Gentoo), and we can do it linearly, without forcing him to have two termina= ls open to see if he has encountered a "different" section, as is currently the case. We can also make the x86/PPC/SPARC/... installation instructions more integrated. Changes in Gentoo are felt all over the place. Currently, the x= 86 installation guide is the guide which is updated quickest. Other installati= on guides follow with some lag. By combining all instructions and have a clear way to denote x86-only, or ppc-only, or sparc-only sections, all architectures are treated equally. We also reduce the total amount of written documentation at first (later on, it'll grow as a natural evolution because of enhancements etc.) since double information is eliminated (if you read the ppc-installation guide for instance, you'll notice that most of it is the same for x86 and vice versa). Now I'm only ranting about the chapter regarding "Installing Gentoo" since, in the GLEP, this is the first chapter that should be worked on. Later, when that chapter is "finished" and official, the guide can and should be extend= ed with other chapters, such as "System Administration", "Gentoo Development", "User Applications" and so on. To provide the Gentoo users with such a handbook, several steps need to be taken. First of all, a new stylesheet (with enhancements for the GuideXML format) should be written. This stylesheet should be able to support - multiple pages output - multiple pages input - deeper nesting of information blocks (chapter, section, subsection, subsubsection) - in-document references and, if possible, a way to convert it to a format that makes it easy to convert to, for instance, LaTeX or DocBook so books can be produced better. Such stylesheet-hocuspocus is not fantasy -- people with experience in XSL know this isn't too hard, but it requires a little time to produce such a stylesheet. In the mean time, development of the installation guide continu= es as it is now. When the stylesheet is finished, a first layout on the chapter should be written. This layout can be a listing of all sections, subsections and subsubsections and should list all guides that are being incorporated, e.g. - x86 installation guide - ppc installation guide - sparc installation guide - alternative installation guide - LVM guide - kernel guide - UML guide - ... Then the chapter can be incorporated. However, to make sure that this doesn= 't lead to spaghetti, we shouldn't add new items yet -- this is for when the chapter becomes official. This way we make sure that the "Installing Gentoo" chapter doesn't stay as an unofficial-work-in-progress. So, please read the GLEP and provide us with your comments! Wkr, Sven Vermeulen PS gentoo-dev ppl, please discuss this in gentoo-doc as this is purely documentation related. --=20 Save some animals, eat a vegetarian. --lteA1dqeVaWQ9QQl Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.2 (GNU/Linux) iD8DBQE/QzBFXfqz7M26L9sRAo04AJoDALcUaHEXYfCOnblem6tQbvAxNwCfXVyn IfSlhjkVGcYEPL2t+2orm8s= =XQYL -----END PGP SIGNATURE----- --lteA1dqeVaWQ9QQl--