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 mailout06.sul.t-online.com ([194.25.134.19]) by cvs.gentoo.org with esmtp (Exim 3.22 #1) id 14hF78-0000zX-00 for gentoo-dev@gentoo.org; Sun, 25 Mar 2001 11:19:52 -0700 Received: from fwd02.sul.t-online.com by mailout06.sul.t-online.com with smtp id 14hF85-00055N-0A; Sun, 25 Mar 2001 20:20:41 +0200 Received: from helios.bagwan (320095285153-0001@[62.155.143.244]) by fwd02.sul.t-online.com with smtp id 14hF7o-0cQRjUC; Sun, 25 Mar 2001 20:20:24 +0200 Received: (qmail 23793 invoked by uid 0); 25 Mar 2001 21:02:39 -0000 Received: from sadchitananda2.bagwan (HELO gottinger.de) (achim@192.168.2.1) by helios.bagwan with SMTP; 25 Mar 2001 21:02:39 -0000 Message-ID: <3ABE3083.6EB43CB6@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 Documentation Considerations References: <3ABE1B4D.7804C925@gottinger.de> <20010325104248.A3589@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: <mailto:gentoo-dev-request@gentoo.org?subject=help> List-Post: <mailto:gentoo-dev@gentoo.org> List-Subscribe: <http://www.gentoo.org/mailman/listinfo/gentoo-dev>, <mailto:gentoo-dev-request@gentoo.org?subject=subscribe> List-Id: Gentoo Linux development list <gentoo-dev.gentoo.org> List-Unsubscribe: <http://www.gentoo.org/mailman/listinfo/gentoo-dev>, <mailto:gentoo-dev-request@gentoo.org?subject=unsubscribe> List-Archive: <http://www.gentoo.org/pipermail/gentoo-dev/> Date: Sun Mar 25 11:20:02 2001 X-Original-Date: Sun, 25 Mar 2001 19:53:07 +0200 X-Archives-Salt: 233851f8-f35a-4a0b-81d6-7f077829497f X-Archives-Hash: ead48fd056610d9ce3e094596647a12c drobbins@gentoo.org wrote: > > On Sun, Mar 25, 2001 at 06:22:37PM +0200, Achim Gottinger wrote: > > > I have a few thoughts how we can handle the documentation for gentoo in a way > > that we can use it for our webpage and independently for a printable book. > > > Now my plan. We separate the articles from the build packages. This means > > we create gentoo-install, gentoo-portage, gentoo-ebuild, gentoo-man which > > contain either gentoo-xsl or docbook style docs and those docs only get > > installed to /usr/share/doc/gentoo/[guide|docbook]. Once daniel has finished > > his gentoo->html xsl stylesheet, I create a gentoo->docbook xsl-sheet. > > Yes, I'd like to use "guide" as our official format and use XSLT to convert > from there. I can focus on the guide -> HTML XSLT, and if you can focus on > the guide -> docbook XSLT, then that would be great. Right now, web page HTML > documentation is our number one priority, but it would also be nice to use > "guide" XML as the master file for our man pages. Can you please make sure that we have the latest xslt-stylesheet on cvs, I want to write a DTD for it: :-/ > > > gentoo-web now can contain an global xml file which is generated dynamic from > > the content of /usr/share/doc/gentoo/guide. It generates the website-content > > from this global file. > > And I'm guessing that we should design it this way so that I need to remerge > the actual documentation before it goes "live" on the website? Because, if > it pulled the docs directly from /usr/portage instead, then it could be using > documentation that's currently in development and not yet production-ready? > > > gentoo-doc must convert the guide-style files to docbook. After that it > > generates a global docbook book file and creates prinatble output. > > OK, so we have the following XML packages, each one containing a master > document in "guide" XML format: > > gentoo-install > gentoo-portage > gentoo-ebuild > gentoo-man > In my eyes a chapter of our book. Take a look how I tried to structure it in gentoo-doc. > Then, we have two "target" packages that generate content from these packages: > > gentoo-web > gentoo-doc These two packages should contain scripts to autogenerate the global xml files. Then the documentation packages can call these scripts on postinstall and prerm. This way your global xml file is allways actual. Additionaly you can add automated html generation of changed parts. This way you must remerge the documentation package to update the webpage. We can even extend ebuild to generate a package-guilde-xml file is /usr/share/doc/gentoo/packages/[category]/[packagename].xml. This files can contain the DESCRIPTION SRC_URI HOME_PAGE tags and maybe some additional cvs info. Additionaly it can include links to /usr/share/doc/[package] stuff. This info could be nice to generate online or local basic packge descriptions in html or even printable. > > > This way we have our docs allways up to date on the web and as a book. > > Sounds good... I'll need to think about how this will work from the webmaster's > (my) perspective. > > -- > Daniel Robbins <drobbins@gentoo.org> > 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