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, DMARC_MISSING,FREEMAIL_FROM,INVALID_DATE,MAILING_LIST_MULTI, RCVD_IN_MSPIKE_H2 autolearn=no autolearn_force=no version=4.0.0 Received: from mailout01.sul.t-online.com ([194.25.134.80]) by cvs.gentoo.org with esmtp (Exim 3.22 #1) id 14eLSt-00034K-00 for gentoo-dev@gentoo.org; Sat, 17 Mar 2001 11:30:12 -0700 Received: from fwd04.sul.t-online.com by mailout01.sul.t-online.com with smtp id 14eLTn-0004p6-02; Sat, 17 Mar 2001 19:31:07 +0100 Received: from helios.bagwan (320095285153-0001@[62.155.143.135]) by fwd04.sul.t-online.com with smtp id 14eLTg-1tl3XUC; Sat, 17 Mar 2001 19:31:00 +0100 Received: (qmail 16963 invoked by uid 0); 17 Mar 2001 21:13:13 -0000 Received: from sadchitananda2.bagwan (HELO gottinger.de) (achim@192.168.2.1) by helios.bagwan with SMTP; 17 Mar 2001 21:13:13 -0000 Message-ID: <3AB3A707.47576446@gottinger.de> From: AGottinger@t-online.de (Achim Gottinger) X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.14 i686) X-Accept-Language: en MIME-Version: 1.0 To: gentoo-dev@gentoo.org Subject: Re: [gentoo-dev] Gentoo Linux documentation References: <20010316144831.B3538@cvs.gentoo.org> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Sender: 320095285153-0001@t-dialin.net 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 X-Reply-To: achim@gentoo.org List-Help: List-Post: List-Subscribe: , List-Id: Gentoo Linux development list List-Unsubscribe: , List-Archive: Date: Sat Mar 17 11:31:02 2001 X-Original-Date: Sat, 17 Mar 2001 19:03:51 +0100 X-Archives-Salt: af995eb8-de74-4739-8364-762169f118ae X-Archives-Hash: fea433fc1a826087777ded08177fe88f drobbins@gentoo.org wrote: > > 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*. There is a lite version of docbook which is not that huge. I'm currently making packages for the docbook-xml-dtd's and docbook(-lite) xsl's. You should be able to test them in a few hours. It's true docbook transformation need much time with these xsl's. But since we do not use dynamic XML generation time should not be the problem. Another thing. I want to make two new categories: - app-spell: (for i/a/pspell, their backendsand the dictionaries. - app-ml: for all the xml/sgml/html whatever ml stuff. Or should ml be a new major categorie with ml-apps and ml-libs subcategories? Then we can put stuff like libwww, libxslt, libxml in ml-libs. And things like jade, sablotron, and all the sgml-tools to ml-apps. achim~ > > 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. > > _______________________________________________ > gentoo-dev mailing list > gentoo-dev@gentoo.org > http://www.gentoo.org/mailman/listinfo/gentoo-dev