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:
The LaTeX style package preamble must support all the options that the XSL stylesheets can pass to the package.
Some packages must be used to make all the thing work.
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.
The latex style file to use is specified by using the option --texstyle . An example of a simple LaTeX DocBook style is provided in the package.
latex_style
The --texstyle option
accepts a package name (no path and no latex_style.sty extension)
or a full style file path. If a full path is used,
the filename must ends with .sty.
# 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
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.
Here is an example of a style package reusing the default docbook style:
Example 4.3. Reused LaTeX style
%%
%% 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}
}
A compliant LaTeX style package supports the following options. The options are provided by the XSL stylesheets according to the document attributes.
| Option | Role |
|---|---|
| hyperlink, nohyperlink | Indicates if links in the document are provided or not |
| article, book | The document is an article or a book |
A LaTeX style package must at least include the following packages.
| Package | Description |
|---|---|
| dbk_core | Core LaTeX definitions and macros needed for DocBook |
All the latex commands beginning with DBK are related to elements under bookinfo or articleinfo.
| Command | Description |
|---|---|
| \DBKreference | mapped to pubsnumber |
| \DBKsite | mapped to address |
| \DBKcopyright | mapped to copyright |
| \DBKdate | mapped to date |
| \DBKedition | mapped to edition |
| \DBKpubdate | mapped to pubdate |
| \DBKsubtitle | mapped to subtitle |
| \DBKreleaseinfo | mapped to releaseinfo |
| \DBKlegalnotice | environment mapped to a legalnotice. 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. |
| \DBKlegalblock | wrapper command for the \DBKlegalnotice environments, used by the latex stylesheet to decide where to put the legal notices in the document. |
| \DBKindexation | This command contains the
othercredit information translated to latex by the XSL.
This command must be placed where the othercredit shall appear in the
document. |
| \DBKindtable | This environnement must be defined by the
user to render the othercredit list. It can be displayed as
a table, listitem, description list, or anything that suits your need.
|
| \DBKinditem | This is an othercredit item. |
| \DBKrevtable | This environnement must be defined by the
user to render the revhistory table. Untill now it is not
really possible to customize it, since it must be a table with four columns,
each column for a revhistory piece of information.
|
| float example | This float is expected to be defined, and
is mapped to example. It is not defined by default by the
dbk_core package to allow the user to define its rendering (ruled or not,
etc.)
|
| float dbequation | This float is expected to be defined, and
is mapped to equation. It is not defined by default by the
dbk_core package to allow the user to define its rendering (ruled or not,
etc.)
|
It is not surprising if your first dblatex compilation fails with a fresh LaTeX style. So, how to debug it when used with dblatex?
The following steps can help you:
Compile your file in the debug mode (option -d).
When the compilation is done, the temporary working directory will not be
removed.
$ dblatex --texstyle=./mystyle.sty -d file.xml ... /tmp/tpub-ben-99629 is not removed
Go under the building temporary directory, and set the environment
with the file env_tex.
$ cd /tmp/tpub-ben-99629 $ . env_tex
Compile the temporary latex file produced by the XSL stylesheets. Its name has the suffix "_tmp.tex".
$ pdflatex file_tmp.tex $ [ many outputs here ]
Now latex stops when it encounters an error so that you can debug your stylesheet.