Re: [gentoo-dev] Gentoo Linux documentation

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

Achim Gottinger wrote:
> 
> 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

I added two new packages

app-text/xmltex 	an XML parser in tex
app-text/passivetex	TeX macros for processing FO formatted xml files.

Now you can convert docbook xml's to pdf's like this:

xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl
install.docbook >install.fo
pdfxmltex install.fo

I get a few errors if I try to convert our install.docbook from
pdfxmltex. In this cases I just hitted enter.
There are a few problems in the resulting install.pdf. The <article>
setion is not supported and the table
does not get formated correct.
Maybe that problems occure because the passivetex macros where written
for another TeX package that tetex.
I will  try to make a package for that tex system (TeX Live). 

achim~

> 
> achim~
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev