<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Customized LaTeX style</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="DocBook to LaTeX Publishing" /><link rel="up" href="sec-custom.html" title="Chapter 4. Customization" /><link rel="prev" href="ch04s04.html" title="XSL User Stylesheet" /><link rel="next" href="sec-texpost.html" title="Latex post process script" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Customized LaTeX style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Customization</th><td width="20%" align="right"> <a accesskey="n" href="sec-texpost.html">Next</a></td></tr></table><hr /></div><div class="section" title="Customized LaTeX style"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-custom-latex"></a>Customized LaTeX style</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="sec-custom-latex.html#idp860240">Reusing an existing LaTeX style</a></span></dt><dt><span class="section"><a href="sec-custom-latex.html#idp3817184">Package options</a></span></dt><dt><span class="section"><a href="sec-custom-latex.html#idm885648">Needed packages</a></span></dt><dt><span class="section"><a href="sec-custom-latex.html#idm1445128">DocBook interface</a></span></dt><dt><span class="section"><a href="sec-custom-latex.html#sec-debug">Debugging your Style</a></span></dt></dl></div><p>
The actual output rendering is done by the latex style package used, and not by the XSL stylesheets whose role is only to translate to latex. Users can provide their own LaTeX style file, in respect of some rules:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
The LaTeX style package preamble must support all the options that the XSL stylesheets can pass to the package.
</p></li><li class="listitem"><p>
Some packages must be used to make all the thing work.
</p></li><li class="listitem"><p>
The docbook interface must be defined: the XSL stylesheets register some elements information in LaTeX commands. These commands or macro are the only ones specific to DocBook that are explicitely used by the XSL stylesheets. Other specific macros are used but are not intended to be changed by the user. These hidden macros are defined in the dbk_core latex package.
</p></li></ul></div><p>
The latex style file to use is specified by using the option <code class="option">--texstyle <em class="replaceable"><code>latex_style</code></em></code>. An example of a simple LaTeX DocBook style is provided in the package.
</p><p>
The <code class="option">--texstyle <em class="replaceable"><code>latex_style</code></em></code> option
accepts a package name (no path and no <code class="filename">.sty</code> extension)
or a full style file path. If a full path is used,
the filename must ends with <code class="filename">.sty</code>.
</p><pre class="programlisting">
# Give a package name and assume its path is already in TEXINPUTS
dblatex --texstyle=mystyle file.xml
# Give the full package path. The TEXINPUTS is then updated by dblatex
dblatex --texstyle=./mystyle.sty file.xml
</pre><div class="section" title="Reusing an existing LaTeX style"><div class="titlepage"><div><div><h3 class="title"><a id="idp860240"></a>Reusing an existing LaTeX style</h3></div></div></div><p>You can either create your latex style from scratch, in respect of the
interfaces described in the following sections, or you can simply reuse an
already existing style and override what you want. The latter method is easier
for small things to change.</p><p>Here is an example of a style package reusing the default docbook
style:</p><div class="example"><a id="idp3329264"></a><p class="title"><strong>Example 4.3. Reused LaTeX style</strong></p><div class="example-contents"><pre class="programlisting">
%%
%% This style is derivated from the docbook one
%%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mystyle}[2007/04/04 My DocBook Style]
%% Just use the original package and pass the options
\RequirePackageWithOptions{docbook}
%% Redefine the paragraph layout
\setlength\parskip{\medskipamount}
\setlength\parindent{5pt}
%% Redefine some french settings
\babelsetup{fr}{%
\catcode`\«=\active
\catcode`\»=\active
\def«{u\og\ignorespaces}
\def»{v\unskip\fg}
}
</pre></div></div><br class="example-break" /></div><div class="section" title="Package options"><div class="titlepage"><div><div><h3 class="title"><a id="idp3817184"></a>Package options</h3></div></div></div><p>A compliant LaTeX style package supports the following options. The options are
provided by the XSL stylesheets according to the document attributes.</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col /></colgroup><thead><tr><th align="left">Option</th><th align="left">Role</th></tr></thead><tbody><tr><td align="center" valign="top">hyperlink, nohyperlink</td><td align="center" valign="top">Indicates if links in the document are provided or not</td></tr><tr><td align="center" valign="top">article, book</td><td align="center" valign="top">The document is an <code class="sgmltag-element">article</code> or a <code class="sgmltag-element">book</code></td></tr></tbody></table></div></div><div class="section" title="Needed packages"><div class="titlepage"><div><div><h3 class="title"><a id="idm885648"></a>Needed packages</h3></div></div></div><p>A LaTeX style package must at least include the following packages.</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col /></colgroup><thead><tr><th align="left">Package</th><th align="left">Description</th></tr></thead><tbody><tr><td align="center" valign="top">dbk_core</td><td align="center" valign="top">Core LaTeX definitions and macros needed for
DocBook</td></tr></tbody></table></div></div><div class="section" title="DocBook interface"><div class="titlepage"><div><div><h3 class="title"><a id="idm1445128"></a>DocBook interface</h3></div></div></div><p>
All the latex commands beginning with DBK are related to elements under <code class="sgmltag-element">bookinfo</code> or <code class="sgmltag-element">articleinfo</code>.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col /></colgroup><thead><tr><th align="left">Command</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left">\DBKreference</td><td align="left">mapped to <code class="sgmltag-element">pubsnumber</code></td></tr><tr><td align="left">\DBKsite</td><td align="left">mapped to <code class="sgmltag-element">address</code></td></tr><tr><td align="left">\DBKcopyright</td><td align="left">mapped to <code class="sgmltag-element">copyright</code></td></tr><tr><td align="left">\DBKdate</td><td align="left">mapped to <code class="sgmltag-element">date</code></td></tr><tr><td align="left">\DBKedition</td><td align="left">mapped to <code class="sgmltag-element">edition</code></td></tr><tr><td align="left">\DBKpubdate</td><td align="left">mapped to <code class="sgmltag-element">pubdate</code></td></tr><tr><td align="left">\DBKsubtitle</td><td align="left">mapped to <code class="sgmltag-element">subtitle</code></td></tr><tr><td align="left">\DBKreleaseinfo</td><td align="left">mapped to <code class="sgmltag-element">releaseinfo</code></td></tr><tr><td align="left">\DBKlegalnotice</td><td align="left">environment mapped to a <code class="sgmltag-element">legalnotice</code>. The legal notices
are all put into the \DBKlegalblock command. It is up to the latex stylesheet to
decide where to put it in the document.</td></tr><tr><td align="left">\DBKlegalblock</td><td align="left">wrapper command for the \DBKlegalnotice environments, used by the latex
stylesheet to decide where to put the legal notices in the document.</td></tr><tr><td align="left">\DBKindexation</td><td align="left">This command contains the
<code class="sgmltag-element">othercredit</code> information translated to latex by the XSL.
This command must be placed where the othercredit shall appear in the
document.</td></tr><tr><td align="left">\DBKindtable</td><td align="left">This environnement must be defined by the
user to render the <code class="sgmltag-element">othercredit</code> list. It can be displayed as
a table, listitem, description list, or anything that suits your need.
</td></tr><tr><td align="left">\DBKinditem</td><td align="left">This is an <code class="sgmltag-element">othercredit</code> item.</td></tr><tr><td align="left">\DBKrevtable</td><td align="left">This environnement must be defined by the
user to render the <code class="sgmltag-element">revhistory</code> table. Untill now it is not
really possible to customize it, since it must be a table with four columns,
each column for a <code class="sgmltag-element">revhistory</code> piece of information.
</td></tr><tr><td align="left">float example</td><td align="left">This float is expected to be defined, and
is mapped to <code class="sgmltag-element">example</code>. It is not defined by default by the
dbk_core package to allow the user to define its rendering (ruled or not,
etc.)
</td></tr><tr><td align="left">float dbequation</td><td align="left">This float is expected to be defined, and
is mapped to <code class="sgmltag-element">equation</code>. It is not defined by default by the
dbk_core package to allow the user to define its rendering (ruled or not,
etc.)
</td></tr></tbody></table></div></div><div class="section" title="Debugging your Style"><div class="titlepage"><div><div><h3 class="title"><a id="sec-debug"></a>Debugging your Style</h3></div></div></div><p>It is not surprising if your first dblatex compilation fails with a fresh
LaTeX style. So, how to debug it when used with dblatex?</p><p>The following steps can help you:</p><div class="procedure"><ol class="procedure" type="1"><li class="step" title="Step 1"><p>Compile your file in the debug mode (option <code class="option">-d</code>).
When the compilation is done, the temporary working directory will not be
removed.
</p><pre class="programlisting">
$ dblatex --texstyle=./mystyle.sty -d file.xml
...
/tmp/tpub-ben-99629 is not removed
</pre><p>
</p></li><li class="step" title="Step 2"><p>Go under the building temporary directory, and set the environment
with the file <code class="filename">env_tex</code>.
</p><pre class="programlisting">
$ cd /tmp/tpub-ben-99629
$ . env_tex
</pre><p>
</p></li><li class="step" title="Step 3"><p>Compile the temporary latex file produced by the XSL stylesheets. Its
name has the suffix "_tmp.tex".
</p><pre class="programlisting">
$ pdflatex file_tmp.tex
$ [ many outputs here ]
</pre><p>
</p></li><li class="step" title="Step 4"><p>Now latex stops when it encounters an error so that you can debug
your stylesheet.
</p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sec-custom.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-texpost.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">XSL User Stylesheet </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Latex post process script</td></tr></table></div></body></html>