<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter>
<title>Introduction</title>

<section>
<title>What about DB2LaTeX?</title>

<para><command>Dblatex</command> started as a <ulink
url="http://db2latex.sourceforge.net">DB2LaTeX</ulink> clone, but since then
many things have changed and new features have been added or (hopefully)
improved. Now, the portion of shared code is small if any, and the dblatex
purpose is different from DB2LaTeX on these points:</para>

<itemizedlist>
<listitem>
<para>The project is end-user oriented, that is, it tries to hide as much as
possible the latex compiling stuff by providing a single clean script to
produce directly DVI, PostScript and PDF output.</para>
</listitem>

<listitem>
<para>The actual output rendering is done not only by the XSL stylesheets
transformation, but also by a dedicated LaTeX package. The goal is to allow a
deep LaTeX customisation without changing the XSL stylesheets.</para>
</listitem>

<listitem>
<para>Post-processing is done by Python, to make publication faster, convert
the images if needed, and do the whole compilation.</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>Features</title>

<para>With <command>dblatex</command> you can:</para>

<itemizedlist>
<listitem>
<para>transform a DocBook XML/SGML book or article to pure LaTeX,</para>
</listitem>

<listitem>
<para>compile the temporary LaTeX file with <command>latex</command>,
<command>pdflatex</command>, or <command>xelatex</command> to produce DVI,
PostScript and PDF files,</para>
</listitem>

<listitem>
<para>publish a set of books,</para>
</listitem>

<listitem>
<para>convert on the fly the figures included in the document,</para>
</listitem>

<listitem>
<para>have cross references with hot links,</para>
</listitem>

<listitem>
<para>olink to other documents built with <command>dblatex</command>,</para>
</listitem>

<listitem>
<para>write complex tables,</para>
</listitem>

<listitem>
<para>write several bibliographies,</para>
</listitem>

<listitem>
<para>reuse BibTeX bibliographies,</para>
</listitem>

<listitem>
<para>use callouts on program listings or on images,</para>
</listitem>

<listitem>
<para>create an index with <command>makeindex</command> or <command>xindy</command>,</para>
</listitem>

<listitem>
<para>write mathematical equations in LaTeX,</para>
</listitem>

<listitem>
<para>write mathematical equations in MathML,</para>
</listitem>

<listitem>
<para>have revision bars,</para>
</listitem>

<listitem>
<para>customise the output rendering with an XSL configuration file,</para>
</listitem>

<listitem>
<para>use your own LaTeX style package.</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>Version</title>

<para>This manual is for dblatex version <xi:include href="version.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"/>.</para>
</section>

<section id="sec-changelog">
<title>Change History</title>

<para>See the <olink output="pdf" targetdoc="releasenotes"
targetptr="intro">Release Notes</olink><ulink output="html"
url="../release-notes/index.html">Release Notes</ulink> to have the dblatex
change history.</para>
</section>

<section>
<title>Publishing Principles</title>

<para>Dblatex transforms a DocBook XML/SGML document to LaTeX. Once
transformed into LaTeX, standard LaTeX tools are used to produce DVI,
Postcript or PDF files.</para>

<para><xref linkend="fig-processus" /> explains the process applied. It shows
the tools used and the steps. The emphasized tools are provided by the
package.</para>

<figure float="0" id="fig-processus">
<title>Transforming Process</title>

<mediaobject>
<imageobject>
<imagedata align="center" fileref="processus" width="60%" />
</imageobject>
</mediaobject>
</figure>

<section id="sec-process">
<title>Backend Drivers</title>

<para>The main script supports the following LaTeX backend drivers:</para>

<variablelist>
<varlistentry>
<term>dvips</term>

<listitem>
<para>The driver calls <command>latex</command>, and produces DVI, Postscript
and at the end PDF files. Latex natively accepts only EPS graphics. The
drawback is that converting to PDF can take a while.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>pdftex</term>

<listitem>
<para>The driver calls <command>pdflatex</command>, to directly produce PDF
files. The conversion is fast, the file size is smaller. Pdflatex natively
accepts PDF, PNG, JPEG, and TIFF graphics.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>xetex</term>

<listitem>
<para>The driver calls <command>xelatex</command>, to directly produce PDF
files through the <ulink url="http://scripts.sil.org/xetex">XeTeX</ulink>
engine. This engine natively supports UTF-8 which improves multilingual
support.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section id="sec-stylesheets">
<title>XSL Stylesheets</title>

<para>The XSL stylesheets located under <filename>xsl/</filename> are used to
transform from XML to “raw” LaTeX. The main file is
<filename>latex_book_fast.xsl</filename>, that includes the other stylesheets
of the directory.</para>
</section>

<section id="sec-perl-process">
<title>Python Post Processing</title>

<para>Actually the XSL stylesheets does not produce valid LaTeX. The reason is
that some DocBook processing is too complex or too time-consuming for XSL
transforming. Besides, some extra actions need sometimes to be done such like
figure conversion. Here are the main actions done by Python Post
processing:</para>

<itemizedlist>
<listitem>
<para>Transform the entities to valid LaTeX characters (e.g. &amp;nbsp; is
transformed to '~'). Python is suited and performant for this task.</para>
</listitem>

<listitem>
<para>Convert the figures to be compatible with the backend driver. See <xref
linkend="sec-figinclude" /> for more detail.</para>
</listitem>

<listitem>
<para>Force some hyphenation in tables or for typed words.</para>
</listitem>

<listitem>
<para>Do the whole LaTeX compilation sequence thanks to the <ulink
url="http://www.pps.jussieu.fr/~beffara/soft/rubber">rubber</ulink>
compilation engine.</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>LaTeX Style Package</title>

<para>Once valid LaTeX is available, the LaTeX style package (docbook.sty)
under <filename>latex/style/</filename> is used to customize the output
rendering. It includes the other files of the directory. You can also provide
your own LaTeX style (cf. <xref linkend="sec-custom" />).</para>
</section>
</section>
</chapter>