DB2LyX Install and Use

B. Guillon


Table of Contents

Introduction
Release
Installing the package
Dependencies
Default Install procedure
Customized Install procedure
Installing XT/XP
Using the stylesheets
Importing an XML file in LyX
Customizing the stylesheets
XSL variables
Extending the stylesheets
Building this document
Documentation structure
Building the LyX file
Building the HTML files
MathML support
References
Limitations -- Bugs
Loss of information
Bugs, problems
Features not yet supported
Thanks
Feedback

Introduction

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.

Release

This paper is for release 0.1.2.

Installing the package

Dependencies

The package needs the following features:

  • the XML DocBook DTD,

  • the Norman Walsh DocBook XSL stylesheets,

  • the MathML ISO entities,

  • the DB2LyX stylesheets,

  • an XSLT.

Default Install procedure

If nothing is installed, you can follow this default install procedure.

  1. Install the XML DocBook DTD.

  2. Install the N. Walsh Docbook XSL stylesheets, let's say in /usr/lib/sgml/xsl/docbook.

  3. Download and install the MathML entities. The default directory where the entities are expected to be placed is /(path)/docbook/mmlents.

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

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

Customized Install procedure

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:

  • The Norman Walsh common stylesheets (/(path)/docbook/common/*).

  • The MathML entities.

So, you need to precise where these two directories are. The install procedure is then:

  1. Install the XML DocBook DTD.

  2. Install the N. Walsh Docbook XSL stylesheets where you want.

  3. Download and install the MathML entities where you want.

  4. Install your favorite XSLT.

  5. Unpack the package where you want:

    > cd /usr/lib/sgml/db2lyx 
    > tar xvzf db2lyx-RELEASE.tar.gz
        
  6. Configure the stylesheets:

    1. Go under the stylesheets root directory:

      > cd docbook/lyx
           
    2. 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
           

   

Installing XT/XP

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:

  1. First, check that java is installed.

  2. Download the XT distribution.

  3. Download an XML parser that supports SAX, let's say XP.

  4. Unzip de XT/XP packages:

    > mkdir /usr/local/xt /usr/local/xp
    > unzip xt.zip -d /usr/local/xt
    > unzip xp.zip -d /usr/local/xp
       
  5. 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
       

Using the stylesheets

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
  

Importing an XML file in LyX

To directly import XML files in LyX, you can create a new converter like this:

  1. Edit the Edit->Preferences->Converters popup

  2. If the XML format does not exist, add the format:

    • Format: xml

    • GUI name: XML

    • Extension: xml

    • Viewer: xemacs

  3. Add the converter XML -> LyX:

    • From: XML

    • To: LyX

    • Converter: java com.jclark.xsl.sax.Driver $$i /(path)/docbook/lyx/docbook.xsl > $$o

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.

Customizing the stylesheets

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.

XSL variables

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

Extending the stylesheets

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
   

Building this document

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.

Documentation structure

The documentation directories are the following:

html:

contains the output HTML files.

outlyx:

contains the output LyX file made by using the package stylesheets on the XML source file.

references:

contains the XML reference files, made from the package stylesheets.

src:

main document source files (manual.lyx and manual.xml).

xsl:

some stylesheets used to produce the XML reference files and HTML files.

Building the LyX file

Content

The files involved in building the ouput LyX file are:

src/manual.lyx:

the original LyX file.

src/manual.xml:

the XML document from the LyX one.

outlyx/Makefile:

a very simple makefile to make manual.out.lyx from manual.xml. It expects that the XSL translator to use is XT.

outlyx/manual-lyx.xsl:

the stylesheet used to create the LyX document. It points to the lyx/docbook.xsl stylesheets.

outlyx/manual.out.lyx:

the output LyX file produced once make is done.

Changing the DTD path

To build the document, you need to set the SYSTEM path to the XML DocBook DTD location of your system, at the top of the manual.xml file:

<?xml version="1.0" encoding="iso-8859-1"?> 
<!DOCTYPE article SYSTEM "file:///[your path here]/docbookx.dtd">
    

Creating the document

If everything is ok:

cd outlyx
make
    

That's it!

Building the HTML files

The document is composed of:

  1. The HTML manual file. This file depends on src/manual.xml.

  2. 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:

  1. Reference XML files production (under references)

  2. HTML files production (under html)

  3. LyX file from the DocBook XML file (under outlyx). This step has no relationship with the preceding steps. It is done because the Makefile tries to update all the document files.

MathML support

A basic MathML support is provided. Only the most common presentation elements are translated.

References

The references are generated automatically from the DB2LyX stylesheets. The following reference entries are available:

Limitations -- Bugs

Loss of information

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.

Bugs, problems

Here are some known bugs. The bug list is not intended to be complete:

  • The file produced is not clean: it contains sometimes too many empty lines, and sometimes some empty lines should be added.

  • Some translations are understood by LyX but it is not really what LyX would do.

  • Problems with quotes and the backslash character.

Features not yet supported

  • Preamble information is not translated. But how to translate it?

  • Many XML tags are not translated.

  • Many XML elements cannot be translated to something known by LyX. Some of these elements are traced in the Unsupported DocBook Elements reference.

Thanks

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!

Feedback

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.