Table of Contents
The DB2LyX package provides a set of XSL stylesheets to translate an XML DocBook document into a LyX-1.1.6 compliant file format. This file is intended to explain how to install and use it, and is the first example of the translation process.
If nothing is installed, the steps to follow are:
Install the N. Walsh Docbook XSL stylesheets, let's say in /usr/lib/sgml/xsl/docbook.
Install your favorite XSLT. XT/XP is a translator that should work correctly with the stylesheets. To install XT/XP look at the XT/XP install procedure.
Unpack the package in the same directory where the N. Walsh XSL stylesheets are installed. The common and lyx directory must be at the same level:
> cd /usr/lib/sgml/xsl/
> tar xvzf db2lyx-RELEASE.tar.gz
You then should have the tree:
/usr/lib/sgml/xsl/docbook
|
+---- bin
+---- common
+---- contrib
...
+---- html
+---- xhtml
+---- lyx
|
+---- ent
+---- doc
XT is the translator used to test the stylesheets, and so it should work correctly on your platform. XT is a set of java libraries, and it needs an XML parser such as XP. Here is an install procedure example:
Download the XT distribution.
Download an XML parser that supports SAX, let's say XP.
> mkdir /usr/local/xt /usr/local/xp > unzip xt.zip -d /usr/local/xt > unzip xp.zip -d /usr/local/xp
Put the XT libraries (xt.jar and sax.jar) and the XP library (xp.jar) in your CLASSPATH:
> CLASSPATH=$CLASSPATH:/usr/local/xt/xt.jar:/usr/local/xt/sax.jar > CLASSPATH=$CLASSPATH:/usr/local/xp/xp.jar > export CLASSPATH
The main stylesheet to give to the XSL translator is docbook.xsl provided by the package. For instance, to translate the file mydoc.xml to mydoc.lyx with XT run the command:
java com.jclark.xsl.sax.Driver mydoc.xml (path)/docbook/lyx/docbook.xsl > mydoc.lyx
To directly import XML files in LyX, you can create a new converter like this:
Once installed, you can directly import an XML file through the menu File->Import->XML. Of course, instead of the DB2LyX docbook stylesheet you can define the converter command such that it points to a customized stylesheet.
Some XSL variables can be modified by the user to customize the XSLT output. Redefining some variables needs to define your own stylesheet. Read the Norman Walsh documentation if you want to have more details about extending the stylesheets.
The following variables are defined to customize the output. These variables are related to some LyX parameters:
| Name | Possible values | Default value |
| lyx.doc.font | One of the Layout->Document->Font list | default |
| lyx.doc.sep | skip or indent | indent |
| lyx.lang.lang | One from the Layout->Document->Lang->Language choice | english |
| lyx.lang.encoding | One from the Layout->Document->Lang->Encoding choice | auto |
| num.section.depth | 1 <= number < 5 | 4 |
| toc.section.depth | 1 <= number < 5 | 4 |
You can extend the stylesheets by defining your own stylesheet to use. To modify the XSL variable or overload an existing template, or add some new behaviour, you need to write your personal stylesheet. Here is a simple example:
<?xml version='1.0'?> <!-- mystyle.xsl --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="/usr/lib/sgml/xsl/docbook/lyx/docbook.xsl"/> <xsl:variable name="lyx.doc.font">default</xsl:variable> <xsl:variable name="lyx.doc.separation">skip</xsl:variable> <xsl:variable name="lyx.lang.lang">spanish</xsl:variable> <xsl:variable name="lyx.lang.encoding">default</xsl:variable> <xsl:variable name="toc.section.depth">5</xsl:variable> </xsl:stylesheet>
Once defined, run the XSL translator on this stylesheet:
java com.jclark.xsl.sax.Driver mydoc.xml mystyle.xsl > mydoc.xml
You can test your configuration and the stylesheets by building the document you are reading now (manual.lyx).
In the directory where this document is (docbook/lyx/doc), are the following files:
the stylesheet used to create the LyX document. It points to the lyx/docbook.xsl stylesheets.
the stylesheet used to create the HTML version of the document.
a very simple makefile to make manual.out.lyx from manual.xml. It expects that the XSL translator to use is XT.
When you write a LyX document, export it to XML and use the stylesheets on this XML output to have a LyX document again, some information from the original LyX file can be lost. The reason is that one can define more information in a LyX document than in an XML one. Here are some information losses examples:
A \newline exported to XML becomes a simple space. So the reverse process cannot translate it into a newline again.
In XML documents exported by LyX, figures do not contain their size, nor their scale. This information cannot be set when translating back to the LyX format.
SGML Style is written as is when LyX exports to XML. The reverse translation cannot know that it was written in an SGML layout paragraph.
The table cell border lines information defined in LyX does not appear in the XML output file. So the reverse translation looses these characteristics.
Thanks to Ramon Casellas who kindly accepted that I use its DB2LaTeX stylesheets as a basis for this package. And thanks to Jose Abilio Oliveira Matos for his support and his patience!
Please give your comments! This is the only way to efficiently improve the package and fix the bugs. To report anything, you can send me an email.