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, you can follow this default install procedure.
Install the N. Walsh Docbook XSL stylesheets, let's say in /usr/lib/sgml/xsl/docbook.
Download and install the MathML entities. The default directory where the entities are expected to be placed is /(path)/docbook/mmlents.
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 +---- mmlents +---- lyx | +---- template +---- doc
The default install procedure allows to use the stylesheets without doing anything but installing the packages in the right directories. With the customized procedure, the external files used by the stylesheets can be located where you want. The external files used by the DB2LyX stylesheets are:
So, you need to precise where these two directories are. The install procedure is then:
Install the N. Walsh Docbook XSL stylesheets where you want.
Download and install the MathML entities where you want.
Unpack the package where you want:
> cd /usr/lib/sgml/db2lyx > tar xvzf db2lyx-RELEASE.tar.gz
Go under the stylesheets root directory:
> cd docbook/lyx
Build the path resolution entities by specifying where the directories are through the base-* variables:
> java com.jclark.xsl.sax.Driver \ template/xslpath.xml template/xslpath.xsl \ base-mmlents=[the MathML entities path] \ base-dbcommon=[the DocBook common directory] > xslpath.ent
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 use 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 set 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, detailed in the Parameters and Variables reference. 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.separation | skip or indent | skip |
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). You can either build only the output LyX file from manual.xml, or building the whole HTML document including the stylesheets references. The subsections consider that the current directory is docbook/lyx/doc.
The documentation directories are the following:
The files involved in building the ouput LyX file are:
a very simple makefile to make manual.out.lyx from manual.xml. It expects that the XSL translator to use is XT.
the stylesheet used to create the LyX document. It points to the lyx/docbook.xsl stylesheets.
The document is composed of:
The HTML references files. These files depend on the XML files under the directory references. The XML reference files depend on the XSL stylesheets of the package, since the reference documentation is included in the stylesheets. The XML files production uses the stylesheets of the directory xsl. Building the HTML files from the XML files need the jrefentry DTD in the references/dtd directory.
To build the HTML document you can simply use the the upper level Makefile (under docbook/lyx/doc). Its operations are:
The references are generated automatically from the DB2LyX stylesheets. The following reference entries are available:
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.
Preamble information is not translated. But how to translate it?
Many XML elements cannot be translated to something known by LyX. Some of these elements are traced in the Unsupported DocBook Elements reference.
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.