Customized LaTeX style
Prev | Chapter 4. Customization | Next

## Customized LaTeX 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 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 `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.

Option | Role
--- | ---
hyperlink, nohyperlink | Indicates if links in the document are provided or not
article, book | The document is an `article` or a `book`

### Needed packages

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

Package | Description
--- | ---
dbk_core | Core LaTeX definitions and macros needed for DocBook

### DocBook interface

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

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

Prev | Up | Next
XSL User Stylesheet | Home | Latex post process script