Re: [gentoo-dev] Gentoo Linux documentation

[AGottinger@t-online.de (Achim Gottinger)]

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                                  <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