AUTHOR
------
Matthew Kennedy <mbkennedy@ieee.org>


LICENSE
-------

Copyright 1999-2002 Gentoo Technologies, Inc.
Distributed under the terms of the GNU General Public License, v2 or later

INTRODUCTION
------------

This tool converts DocBook XML V3.1 into Gentoo Guide XML. It achieves
this using an XSLT, which is the ideal way to convert XML to XML.

WHERE THIS TOOL FITS INTO THE COSMOS
------------------------------------
                       -----------        ------------
   Lyx exported        |          |       
   DocBook 3.1   ----> | sgml2xml | ---->  DocBook 3.1
   SGML                |          |        XML
                       ------------       ------------
                                               |
                                               |
                                               |
                                               V
                       -----------        ------------
   Gentoo              |         |        |          |
   Guide         <---- |xsltproc | <----- |  THIS    |
   XML 2.1             |         |        |  TOOL    |
                       -----------        ------------
                           A                  A
                           |                  |
                           |                  |
                       -----------       --------------
 
                     gentoo-main.xsl   lyx-to-gentoo.xslt
                       -----------       --------------

Thus it's a bridge between Lyx documents and Gentoo Guide XML. ie. you
can use Lyx to create Gentoo guides.

PREREQUISITES
-------------

This tool was developed with Xalan, an XLST engine developed by the
Apache foundation. Other XSLT engines may work (such as xsltproc), but
this hasn't been tested.

Since Xalan is a prerequisite, so too is Java. You need at least a
Java 2 SE 1.3.0 JVM. This tool has been tested with Sun's Java 2 SDK
1.4.0.

FILES INCLUDED
--------------

* lyx-to-gentoo.xslt

  This is the XSLT for converting DocBook 3.1 XML to Gentoo Guide XML.

* README

  This file.

* xalan

  A simple wrapper script which invokes Xalan from the command line
  and other scripts. 

GETTING STARTED
---------------

1. Install Xalan -- grab
http://xml.apache.org/dist/xalan-j/xalan-j_2_3_1-bin.tar.gz and un-tar
it to some place (I recommend $HOME/lib).

2. Edit the xalan wrapper script and set XALAN_HOME to where your
Xalan directory is. If you un-tar'd it to $HOME/lib, then XALAN_HOME
should be set to "$HOME/xalan-j_2_3_1"

3. Use sgml2xml to convert the Lyx-export SGML to XML. The output
filename can be anything, but for this tutorial, let's say it's named
"myguide-from-lyx.xml"

4. Use this tool to convert myguide-from-lyx.xml to Gentoo Guide XML:

    $ ./xalan -IN myguide-from-lyx.xml -XSL lyx-to-gentoo.xslt >myguide-as-gentoo.xml

5. Then for the final step, actually create the guide as HTML etc.

    $ xsltproc gentoo-main.xsl myguide-as-gentoo.xml myguide-as-gentoo.html


As you can see, all the effort goes into lyx-to-gentoo.xslt. The
advantage is it's flexible, just edit lyx-to-gentoo.xslt to taste and
re-run. There are more comments/hints/documentation in
lyx-to-gentoo.xslt.

LIMITATIONS
-----------

Not everything in DocBook 3.1 XML maps into Gentoo Guide XML and vice
versa (although the formats are very similar in structure). Currently,

 * author/abstract/date/version elements cannot be mapped becasue Lyx
   does not seem to support them. I am not very familiar with Lyx
   though.

 * DocBook 3.1 supports a SECT3 element. SECT1 and SECT2 map to Gentoo
   Guide XML chapter and section elements, but there isn't support for
   the deeper SECT3 map (it would be nice though if Gentoo Guide XML
   supported recursive sections). As a work around, this tool makes
   use of the Gentoo Guide XML "i" element to achive the same visual
   outcome. See lyx-to-gentoo.xslt for more detail on this.