Using DB2LaTeX

Common output formats for DocBook are HTML (or XHTML) and PDF. PDF output uses a two-stage toolchain. First, you will need to transform your DocBook source files into a typesetting format. Then, you need to typeset the document to produce PDF. For DB2LaTeX, the typesetter is LaTeX (including pdfTeX). It use useful to create a ‘Makefile’ to build your printable document on an ongoing basis. DB2LaTeX allows you to combine DocBook with existing LaTeX systems such as BibTeX and makeindex.

To transform a XML document using XSL stylesheets you need an XSLT processor. There are several commercial and free XSLT processors available. To use the DB2LaTeX stylesheets, your processor will need support for XSLT 1.0 and XPath 1.0 (you do not need XInclude or extensions support). The processor must support XSL ‘keys’. (Some processors have broken ID support, but DB2LaTeX will use keys to avoid this pitfall and others.)

Basically, all XSLT processors are invoked with three parameters: the input XML document, the XSLT stylesheet to apply, and the (optional) output filename. The syntax depends on your processor. This guide includes examples for xsltproc and Saxon.

Preparing to Invoke Your Processor

1. Choosing a Processor

1.1. What Processor Should I Use?

1.2. How are Processors Installed?

2. Using a Processor

2.1. Do I Need to use Resolvers and Catalogues?

2.2. Do I Need to use Extensions?

2.3. Do I Need Special Capabilities

1. Choosing a Processor
1.1. What Processor Should I Use? 1.2. How are Processors Installed?
1.1.	What Processor Should I Use?
	People choose different XSLT processors based on criteria such as availability, speed, interface features, support for new standards, and support for extensions. It is known that xsltproc, Xalan-Java and Saxon can process DocBook documents. xsltproc is most easy to use, it is very fast, and most users will prefer to use it. However, various versions of xsltproc suffer from a number of bugs that can cause intermittent failures or incorrect output. Saxon is more cumbersome but is also more reliable. Note People have used XT with DocBook in the past. However, it does not support some XSL features (such as keys). Some Well-known XSLT Processors xsltproc (popular option, but suffers intermittent failures or invalid output) Saxon (very reliable, but slower than xsltproc in many circumstances) Xalan-Java Sablotron (success not yet reported for DB2LaTeX)
1.2.	How are Processors Installed?
	XSLT processors are easy to install (there is usually no ‘installation’ actually needed). For package-managed operating systems, an xsltproc (or libxslt) package is probably available. If you install a Java- or Perl-based processor (such as Saxon) you will need to have installed Java or Perl installed.
2. Using a Processor
2.1. Do I Need to use Resolvers and Catalogues? 2.2. Do I Need to use Extensions? 2.3. Do I Need Special Capabilities
2.1.	Do I Need to use Resolvers and Catalogues?
	We recommend that you set up a resolver for all your DocBook XML work. This includes keeping local copies of the DTDs and DB2LaTeX stylesheets. However, this is not technically necessary.
2.2.	Do I Need to use Extensions?
	There are no extensions specifically provided for DB2LaTeX.
2.3.	Do I Need Special Capabilities
	DB2LaTeX requires only XSLT 1.0 and XSL 1.0.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

XML files often contain references to other XML files or DTDs. For instance, DOCTYPE declarations contain ‘public’ or ‘system’ identifiers. Additionally, XSL files may contain URLs to locate other XSL files. These identifiers and locators may refer to resources on your local computer or on ‘remote hosts’. Often, users will choose to store a local mirror of something that originated on a remote host.

When processing DocBook files, your XSLT processor will require access to the DocBook DTDs and the DB2LaTeX stylesheets. The ‘canonical’ URLs for these resources are public web hosts in the United States of America. Your XSLT processor will therefore attempt to load the DTDs and stylesheets from the web. However, this is slow and may be costly. Resolver catalogues can provide your processor with a means of using local mirrors rather than canonical sources.

Also, you may sometimes use a local filesystem locator when you are writing your own stylesheets. This could make your files non-portable. Resolver catalogues can be used to solve this problem without having to rewrite your files (or files that you received from other people).

Getting Started with a Resolver

1. XSLT Processor Support for Resolvers and Catalogues

1.1. Does my XSLT Processor Support a Resolver?

2. Setting up Catalogues

2.1. How do I Set Up an XML Catalogue?

3. Using Your Resolver

3.1. How do I Use an XML Catalogue with xsltproc?

3.2. How do I Use an XML Catalogue with Saxon and Sun's Resolver?

3.3. How do I Use an XML Catalogue with Xalan-Java and Sun's Resolver?

1. XSLT Processor Support for Resolvers and Catalogues
1.1. Does my XSLT Processor Support a Resolver?
1.1.	Does my XSLT Processor Support a Resolver?
	It is widely known that xsltproc (libxml2), Saxon and Xalan-Java support entity and URI resolution. Saxon and Xalan-Java need you to supply resolver classes to fulfil this role. Resolver Support libxml2 (see also libxslt) Sun's Resolver for Java (Norman Walsh)
2. Setting up Catalogues
2.1. How do I Set Up an XML Catalogue?
2.1.	How do I Set Up an XML Catalogue?
	Warning This example uses file paths that are specific to one computer. Your computer may require different paths. Here is an example that provides local copies of the DocBook DTDs, Norman Walsh's XSL Stylesheets, and DB2LaTeX. <?xml version="1.0"?> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <!-- map DOCTYPE public identifiers to local copies --> <public publicId="-//OASIS//DTD DocBook XML V4.2//EN" uri="/usr/local/share/xml/docbook/4.2/docbookx.dtd"/> <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" uri="/usr/local/share/xml/docbook/4.1.2/docbookx.dtd"/> <public publicId="-//OASIS//DTD DocBook XML V4.0//EN" uri="/usr/local/share/xml/docbook/4.1.2/docbookx.dtd"/> <public publicId="-//OASIS//DTD DocBook XML V3.1//EN" uri="/usr/local/share/xml/docbook/4.2/docbookx.dtd"/> <!-- map DOCTYPE system identifiers to local copies --> <system systemId="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" uri="/usr/local/share/xml/docbook/4.2/docbookx.dtd"/> <system systemId="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" uri="/usr/local/share/xml/docbook/4.1.2/docbookx.dtd"/> <system systemId="http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" uri="/usr/local/share/xml/docbook/4.1.2/docbookx.dtd"/> <!-- map URLs to local files --> <rewriteURI uriStartString="http://db2latex.sourceforge.net/xsl/" rewritePrefix="/export/user/me/source/docbook/db2latex/xsl/"/> <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="/export/user/me/source/docbook/docbook-xsl/"/> </catalog> If this were being used with Sun's resolver (see above), you could use this CatalogManager.properties: # Enable this to help check that your local files are being found and used: #verbosity=4 relative-catalogs=no # Always use semicolons in this list catalogs=catalogue.xml prefer=system static-catalog=yes catalog-class-name=com.sun.resolver.Resolver
3. Using Your Resolver
3.1. How do I Use an XML Catalogue with xsltproc? 3.2. How do I Use an XML Catalogue with Saxon and Sun's Resolver? 3.3. How do I Use an XML Catalogue with Xalan-Java and Sun's Resolver?
3.1.	How do I Use an XML Catalogue with xsltproc?
	If you are using xsltproc under a UNIX-like system then you can place your catalogue file at /etc/xml/catalog and xsltproc will use it by default.
3.2.	How do I Use an XML Catalogue with Saxon and Sun's Resolver?
	Ensure that resolver.jar and CatalogManager.properties are in the Java classpath for Saxon. Tell Saxon to use Sun's resolver. For example, use the following command-line arguments: -r com.sun.resolver.tools.CatalogResolver -x com.sun.resolver.tools.ResolvingXMLReader -y com.sun.resolver.tools.ResolvingXMLReader
3.3.	How do I Use an XML Catalogue with Xalan-Java and Sun's Resolver?
	Ensure that resolver.jar and CatalogManager.properties are in the Java classpath for Xalan-Java. Tell Xalan-Java to use Sun's resolver. For example, use the following command-line arguments: -URIRESOLVER com.sun.resolver.tools.CatalogResolver -ENTITYRESOLVER com.sun.resolver.tools.CatalogResolver

Create a source document using your favourite editor (it's vim, right?).

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="ArticleId" lang="en">
<articleinfo>
<title> A short introduction to the XSL LaTeX
Stylesheets in the framework of the DocBook DTD. </title>
<authorgroup>
        <author> <surname>Casellas</surname> <firstname>Ramon</firstname> </author>
        <corpauthor>Ecole Nationale Superieure des Telecommunications</corpauthor>
</authorgroup>
</articleinfo>

<abstract><para> Most articles start with a nice abstract, which is usually left for 
the very last moment, and consists of several short sentences cut and
pasted basically from the introduction.  </para></abstract>

<sect1><title>Introduction</title>
<para> This paper.... the purpose of this work... highlights...
Extensive simulations.... Numerical Results ...
</para>
</sect1>


<bibliography><title>Bibliographie</title>
<biblioentry id="PimPum" xreflabel="PimPum">
<abbrev>PimPum</abbrev>
        <title>" Pim Pam Pum"</title>
        <authorgroup>
                <author><firstname>James</firstname><surname>Pim</surname></author>
                <author><firstname>Robert</firstname><surname>Pum</surname></author>
        </authorgroup>
        <publisher>
                <publishername>Get a Life International Editions.
                ISBN 0-XS-xsxs-1</publishername>
        </publisher>
        <pubdate>2001</pubdate>
</biblioentry>

</bibliography>
</article>

Often, you will want to customise DB2LaTeX. For this, you will need to create a "driver" file (an XSL stylesheet). This "customisation layer" is explained in our customisation guide. For the purposes of illustration, a small driver file is illustrated:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
    <xsl:import href="http://db2latex.sourceforge.net/xsl/docbook.xsl"/>
    <!-- optionally, insert your customisations here -->
</xsl:stylesheet>

The next step is to transform your DocBook source file using your favourite XSLT processor. See the documentation of your XSLT processor for details. For xsltproc:

xsltproc -o mydb2latex.tex mydb2latex.xsl mydb2latex.xml

For Saxon:

java -cp /usr/share/java/saxon.jar:..:/my/home/resolver.jar \
  com.icl.saxon.StyleSheet -r com.sun.resolver.tools.CatalogResolver \
  -x com.sun.resolver.tools.ResolvingXMLReader \
  -y com.sun.resolver.tools.ResolvingXMLReader \
  -o mydb2latex.tex mydb2latex.xml mydb2latex.xsl

The resulting file will look similar to:

% ----------------------- Preamble
\documentclass[english,a4]{article}
%
% ... DB2LaTeX preamble ...
%
\title{A short introduction to the XSL LaTeX
Stylesheets in the framework of the DocBook DTD.}
\author{Ramon Casellas}
\begin{document}

\maketitle

% --------------------------------------------
% Abstract
% --------------------------------------------
\begin{abstract}

Most articles start with a nice abstract, which is usually left for
the very last moment, and consists of several short sentences cut and
pasted basically from the introduction.

\end{abstract}

\section{Introduction}
\label{N2624}\hypertarget{N2624}{}

 This paper.... the purpose of this work... highlights...
Extensive simulations.... Numerical Results ...


% -------------------------------------------
%
%  Bibliography
%
% -------------------------------------------
\begin{thebibliography}{WIDELABEL}

% -------------- biblioentry
\bibitem[PimPum]{PimPum}
James Pim and Robert Pum, \emph{" Pim Pam Pum", } Get a Life International Editions.
ISBN 0-XS-xsxs-1, 2001, .
\label{PimPum}\hypertarget{PimPum}{}

\end{thebibliography}

% --------------------------------------------
% End of document
% --------------------------------------------
\end{document}

You will now want to typeset this LaTeX file into a display format such as DVI or PDF. For pdfTeX:

pdflatex mydb2latex.tex && acroread mydb2latex.pdf

In some cases, you will need to run your typesetter twice or invoke an ancillary programme like makeindex:

pdflatex mydb2latex
makeindex mydb2latex
pdflatex mydb2latex
acroread mydb2latex.pdf