Customized LaTeX style

Reusing an existing LaTeX style
Package options
Needed packages
DocBook interface
Debugging your Style

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 file to use is specified by using the option --texstyle latex_style. An example of a simple LaTeX DocBook style is provided in the package.

The --texstyle latex_style option accepts a package name (no path and no .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

Reusing an existing LaTeX style

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}
}


Package options

A compliant LaTeX style package supports the following options. The options are provided by the XSL stylesheets according to the document attributes.

OptionRole
hyperlink, nohyperlinkIndicates if links in the document are provided or not
article, bookThe document is an article or a book

Needed packages

A LaTeX style package must at least include the following packages.

PackageDescription
dbk_coreCore LaTeX definitions and macros needed for DocBook

DocBook interface

All the latex commands beginning with DBK are related to elements under bookinfo or articleinfo.

CommandDescription
\DBKreferencemapped to pubsnumber
\DBKsitemapped to address
\DBKcopyrightmapped to copyright
\DBKdatemapped to date
\DBKeditionmapped to edition
\DBKpubdatemapped to pubdate
\DBKsubtitlemapped to subtitle
\DBKreleaseinfomapped to releaseinfo
\DBKlegalnoticeenvironment 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.
\DBKlegalblockwrapper command for the \DBKlegalnotice environments, used by the latex stylesheet to decide where to put the legal notices in the document.
\DBKindexationThis command contains the othercredit information translated to latex by the XSL. This command must be placed where the othercredit shall appear in the document.
\DBKindtableThis 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.
\DBKinditemThis is an othercredit item.
\DBKrevtableThis 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 exampleThis 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 dbequationThis 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.)

Debugging your Style

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:

  1. 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
    

  2. Go under the building temporary directory, and set the environment with the file env_tex.

    $ cd /tmp/tpub-ben-99629
    $ . env_tex
    

  3. Compile the temporary latex file produced by the XSL stylesheets. Its name has the suffix "_tmp.tex".

    $ pdflatex file_tmp.tex
    $ [ many outputs here ]
    

  4. Now latex stops when it encounters an error so that you can debug your stylesheet.