1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!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>
<sect1>
<title>Why a DB2LaTeX clone?</title>
<para>dblatex is actually a <ulink url="http://db2latex.sourceforge.net">DB2LaTeX</ulink> clone. So, why this project? The purpose is a bit different 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 purpose 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></sect1>
<sect1>
<title>
Features
</title>
<para>
With dblatex 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 latex or pdflatex, to produce DVI, PostScript and PDF files, </para>
</listitem>
<listitem>
<para> convert on the fly the figures included in the document, </para>
</listitem>
<listitem>
<para> write complex tables, </para>
</listitem>
<listitem>
<para> write several bibliographies, </para>
</listitem>
<listitem>
<para> use callouts on program listings or on images, </para>
</listitem>
<listitem>
<para> create an index, </para>
</listitem>
<listitem>
<para> write mathematical equations in LaTeX, </para>
</listitem>
<listitem>
<para> write mathematical equation 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>
</sect1>
<sect1>
<title>
Version
</title>
<para>
This manual is for dblatex version <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="version.xml"/>.
</para>
</sect1>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="changes/changes.xml"/>
<sect1>
<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 id="fig-processus" float="0">
<title>Transforming Process</title>
<mediaobject><imageobject>
<imagedata fileref="processus" align="center" width="60%"/>
</imageobject></mediaobject></figure>
<sect2 id="sec-process">
<title>
Backend Drivers
</title>
<para>
The main script allows to use two LaTeX backend drivers:
</para>
<itemizedlist>
<listitem>
<para>
The “dvips” 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>
<listitem>
<para>
The “pdftex” driver calls <command>pdflatex</command>, to produce directly PDF files. The conversion is fast, the file size is smaller. Pdflatex natively
accepts PDF, PNG, JPEG, and TIFF graphics.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 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>
</sect2>
<sect2 id="sec-perl-process">
<title>Python Post Processing</title>
<para>
Actually the XSL stylesheets doesn't 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. &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>
</sect2>
<sect2>
<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>
</sect2>
</sect1>
</chapter>
|
