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=1.5 required=5.0 tests=DATE_IN_PAST_12_24, DMARC_MISSING,FREEMAIL_FROM,INVALID_DATE,MAILING_LIST_MULTI, RCVD_IN_MSPIKE_H2,RDNS_NONE,SPOOFED_FREEMAIL_NO_RDNS autolearn=no autolearn_force=no version=4.0.0 Received: from [194.25.134.19] (helo=mailout06.sul.t-online.com) by cvs.gentoo.org with esmtp (Exim 3.22 #1) id 14eMwr-0003II-00 for gentoo-dev@gentoo.org; Sat, 17 Mar 2001 13:05:16 -0700 Received: from fwd03.sul.t-online.com by mailout06.sul.t-online.com with smtp id 14eMxU-0007B8-0H; Sat, 17 Mar 2001 21:05:52 +0100 Received: from helios.bagwan (320095285153-0001@[62.155.143.135]) by fwd03.sul.t-online.com with smtp id 14eMxQ-1nshjkC; Sat, 17 Mar 2001 21:05:48 +0100 Received: (qmail 16997 invoked by uid 0); 17 Mar 2001 22:48:06 -0000 Received: from sadchitananda2.bagwan (HELO gottinger.de) (achim@192.168.2.1) by helios.bagwan with SMTP; 17 Mar 2001 22:48:06 -0000 Message-ID: <3AB3BD44.AF579A3B@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> <3AB3A707.47576446@gottinger.de> 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 13:06:02 2001 X-Original-Date: Sat, 17 Mar 2001 20:38:44 +0100 X-Archives-Salt: 1be18ebb-083c-4983-b0aa-88e492e029b8 X-Archives-Hash: 62c84065aeab15b6427f66b568bdd138 Achim Gottinger wrote: > > 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. I have commited all the required packages. You will need app-text/docbook-xml DTD's app-text/docbook-xml-simplified DTD's app-text/docbook-xsl XSL Stylesheets for XML->HTML and XML->FO transformation gnome-libs/libxml2 required for libxslt gnome-libs/libxslt includes the required xsltproc. Once you have installed all these, you can transform install.docbook to html with the following command: xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl install.docbook > install.html If you want to disable dtd validation use the option --novalid achim~