|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
Packit |
0f19cf |
<chapter>
|
|
Packit |
0f19cf |
<title>Introduction</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section>
|
|
Packit |
0f19cf |
<title>What about DB2LaTeX?</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para><command>Dblatex</command> started as a
|
|
Packit |
0f19cf |
url="http://db2latex.sourceforge.net">DB2LaTeX</ulink> clone, but since then
|
|
Packit |
0f19cf |
many things have changed and new features have been added or (hopefully)
|
|
Packit |
0f19cf |
improved. Now, the portion of shared code is small if any, and the dblatex
|
|
Packit |
0f19cf |
purpose is different from DB2LaTeX on these points:</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<itemizedlist>
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>The project is end-user oriented, that is, it tries to hide as much as
|
|
Packit |
0f19cf |
possible the latex compiling stuff by providing a single clean script to
|
|
Packit |
0f19cf |
produce directly DVI, PostScript and PDF output.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>The actual output rendering is done not only by the XSL stylesheets
|
|
Packit |
0f19cf |
transformation, but also by a dedicated LaTeX package. The goal is to allow a
|
|
Packit |
0f19cf |
deep LaTeX customisation without changing the XSL stylesheets.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>Post-processing is done by Python, to make publication faster, convert
|
|
Packit |
0f19cf |
the images if needed, and do the whole compilation.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</itemizedlist>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section>
|
|
Packit |
0f19cf |
<title>Features</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>With <command>dblatex</command> you can:</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<itemizedlist>
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>transform a DocBook XML/SGML book or article to pure LaTeX,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>compile the temporary LaTeX file with <command>latex</command>,
|
|
Packit |
0f19cf |
<command>pdflatex</command>, or <command>xelatex</command> to produce DVI,
|
|
Packit |
0f19cf |
PostScript and PDF files,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>publish a set of books,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>convert on the fly the figures included in the document,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>have cross references with hot links,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>olink to other documents built with <command>dblatex</command>,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>write complex tables,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>write several bibliographies,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>reuse BibTeX bibliographies,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>use callouts on program listings or on images,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>create an index with <command>makeindex</command> or <command>xindy</command>,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>write mathematical equations in LaTeX,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>write mathematical equations in MathML,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>have revision bars,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>customise the output rendering with an XSL configuration file,</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>use your own LaTeX style package.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</itemizedlist>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section>
|
|
Packit |
0f19cf |
<title>Version</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>This manual is for dblatex version
|
|
Packit |
0f19cf |
xmlns:xi="http://www.w3.org/2001/XInclude"/>.</para>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section id="sec-changelog">
|
|
Packit |
0f19cf |
<title>Change History</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>See the
|
|
Packit |
0f19cf |
targetptr="intro">Release Notes</olink>
|
|
Packit |
0f19cf |
url="../release-notes/index.html">Release Notes</ulink> to have the dblatex
|
|
Packit |
0f19cf |
change history.</para>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section>
|
|
Packit |
0f19cf |
<title>Publishing Principles</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>Dblatex transforms a DocBook XML/SGML document to LaTeX. Once
|
|
Packit |
0f19cf |
transformed into LaTeX, standard LaTeX tools are used to produce DVI,
|
|
Packit |
0f19cf |
Postcript or PDF files.</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para><xref linkend="fig-processus" /> explains the process applied. It shows
|
|
Packit |
0f19cf |
the tools used and the steps. The emphasized tools are provided by the
|
|
Packit |
0f19cf |
package.</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<figure float="0" id="fig-processus">
|
|
Packit |
0f19cf |
<title>Transforming Process</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<mediaobject>
|
|
Packit |
0f19cf |
<imageobject>
|
|
Packit |
0f19cf |
<imagedata align="center" fileref="processus" width="60%" />
|
|
Packit |
0f19cf |
</imageobject>
|
|
Packit |
0f19cf |
</mediaobject>
|
|
Packit |
0f19cf |
</figure>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section id="sec-process">
|
|
Packit |
0f19cf |
<title>Backend Drivers</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>The main script supports the following LaTeX backend drivers:</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<variablelist>
|
|
Packit |
0f19cf |
<varlistentry>
|
|
Packit |
0f19cf |
<term>dvips</term>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>The driver calls <command>latex</command>, and produces DVI, Postscript
|
|
Packit |
0f19cf |
and at the end PDF files. Latex natively accepts only EPS graphics. The
|
|
Packit |
0f19cf |
drawback is that converting to PDF can take a while.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</varlistentry>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<varlistentry>
|
|
Packit |
0f19cf |
<term>pdftex</term>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>The driver calls <command>pdflatex</command>, to directly produce PDF
|
|
Packit |
0f19cf |
files. The conversion is fast, the file size is smaller. Pdflatex natively
|
|
Packit |
0f19cf |
accepts PDF, PNG, JPEG, and TIFF graphics.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</varlistentry>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<varlistentry>
|
|
Packit |
0f19cf |
<term>xetex</term>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>The driver calls <command>xelatex</command>, to directly produce PDF
|
|
Packit |
0f19cf |
files through the <ulink url="http://scripts.sil.org/xetex">XeTeX</ulink>
|
|
Packit |
0f19cf |
engine. This engine natively supports UTF-8 which improves multilingual
|
|
Packit |
0f19cf |
support.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</varlistentry>
|
|
Packit |
0f19cf |
</variablelist>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section id="sec-stylesheets">
|
|
Packit |
0f19cf |
<title>XSL Stylesheets</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>The XSL stylesheets located under <filename>xsl/</filename> are used to
|
|
Packit |
0f19cf |
transform from XML to “raw” LaTeX. The main file is
|
|
Packit |
0f19cf |
<filename>latex_book_fast.xsl</filename>, that includes the other stylesheets
|
|
Packit |
0f19cf |
of the directory.</para>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section id="sec-perl-process">
|
|
Packit |
0f19cf |
<title>Python Post Processing</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>Actually the XSL stylesheets does not produce valid LaTeX. The reason is
|
|
Packit |
0f19cf |
that some DocBook processing is too complex or too time-consuming for XSL
|
|
Packit |
0f19cf |
transforming. Besides, some extra actions need sometimes to be done such like
|
|
Packit |
0f19cf |
figure conversion. Here are the main actions done by Python Post
|
|
Packit |
0f19cf |
processing:</para>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<itemizedlist>
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>Transform the entities to valid LaTeX characters (e.g. is
|
|
Packit |
0f19cf |
transformed to '~'). Python is suited and performant for this task.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>Convert the figures to be compatible with the backend driver. See
|
|
Packit |
0f19cf |
linkend="sec-figinclude" /> for more detail.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>Force some hyphenation in tables or for typed words.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<listitem>
|
|
Packit |
0f19cf |
<para>Do the whole LaTeX compilation sequence thanks to the
|
|
Packit |
0f19cf |
url="http://www.pps.jussieu.fr/~beffara/soft/rubber">rubber</ulink>
|
|
Packit |
0f19cf |
compilation engine.</para>
|
|
Packit |
0f19cf |
</listitem>
|
|
Packit |
0f19cf |
</itemizedlist>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<section>
|
|
Packit |
0f19cf |
<title>LaTeX Style Package</title>
|
|
Packit |
0f19cf |
|
|
Packit |
0f19cf |
<para>Once valid LaTeX is available, the LaTeX style package (docbook.sty)
|
|
Packit |
0f19cf |
under <filename>latex/style/</filename> is used to customize the output
|
|
Packit |
0f19cf |
rendering. It includes the other files of the directory. You can also provide
|
|
Packit |
0f19cf |
your own LaTeX style (cf. <xref linkend="sec-custom" />).</para>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
</section>
|
|
Packit |
0f19cf |
</chapter>
|