From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 4.0.0 (2022-12-14) on finch.gentoo.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DATE_IN_PAST_12_24, INVALID_DATE,MAILING_LIST_MULTI,NO_RELAYS autolearn=no autolearn_force=no version=4.0.0 Received: from drobbins by cvs.gentoo.org with local (Exim 3.22 #1) id 14e25H-00010G-00 for gentoo-dev@gentoo.org; Fri, 16 Mar 2001 14:48:31 -0700 To: gentoo-dev@gentoo.org Message-ID: <20010316144831.B3538@cvs.gentoo.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i From: Subject: [gentoo-dev] Gentoo Linux documentation Sender: gentoo-dev-admin@gentoo.org Errors-To: gentoo-dev-admin@gentoo.org X-BeenThere: gentoo-dev@gentoo.org X-Mailman-Version: 2.0 Precedence: bulk Reply-To: gentoo-dev@gentoo.org List-Help: List-Post: List-Subscribe: , List-Id: Gentoo Linux development list List-Unsubscribe: , List-Archive: Date: Fri Mar 16 14:49:02 2001 X-Original-Date: Fri, 16 Mar 2001 14:48:31 -0700 X-Archives-Salt: 3612a964-35f3-4d40-8eb9-3eb6ad1550ea X-Archives-Hash: 1f6b85e15e2128aeceaf90453c3c5b30 Hi All, In a few days, we're going to start an official documentation rampage, lasting about a week. Hopefully, in that time, we can get a whole bunch of documentation done and on the website. Fortunately, I'm writing an article for IBM on the website redesign, so I can devote some time to documentation. However, this does mean that our doc solution will be scrutinized by the world, but I figured we're up to the task. For a refresher, this is what everybody seems to be in agreement upon: 1. The documentation should be composed in XML. 2. We should use XSLT to translate the XML documentation into web-ready HTML. However, we still haven't decided which XML approach to use: a. Use our own custom "guide" format designed for our needs b. Use the already complete docbook format for our XML In my eyes, the advantage of a custom guide format is that it is much easier to change/upgrade if we need new features, and is definitely going to have a simpler, more HTML-like syntax. The advantage of the docbook format is that it's a standard (for technical documentation), and has a lot of features. The downside of this is that we are less in control of the format and we will need to learn the "docbook way" of doing things. Another concern about docbook -- since it has a lot more tags than our lightweight guide format, writing docbook --> HTML XSL transforms could be *very* cumbersome, since we will have to support all docbook tags :( This appears to be the major drawback to docbook -- its DTD is *huge*. example docbook XML: /usr/portage/app-doc/gentoo-doc/files/install.docbook example guide (beta) XML: /usr/portage/app-doc/gentoo-web/files/xml/install.xml -- Daniel Robbins President/CEO http://www.gentoo.org Gentoo Technologies, Inc.