# Customization

The transformation process (and thus the output rendering) can be heavily customized by:

- using some configuration parameters either in a configuration stylesheet or directly from the command line,

- using some customized stylesheets,

- using a customized LaTeX style package.

- using a LaTeX post process script or plugin.

All these customization methods can be used independently and in exceptional cases, but it can also be combined and registered in a master configuration file, called a specification file (cf. ) to create a new tool dedicated to your needs.

## Using XSL Parameters

The PDF rendering can be customised by using some XSL configuration parameters. contains the reference documentation of the available user-configurable parameters.

## Setting Command line Parameters

You can set some XSL parameters directly from the command line without creating a configuration parameter stylesheet, with the `-P parameter=value` option.

The following example set the latex.hyperparam parameter value:

      dblatex -P latex.hyperparam=colorlinks,linkcolor=blue myfile.xml

## XSL User Stylesheet

You can provide your own XSL stylesheet to set some of the XSL parameters, and/or to override some of the dblatex XSL templates. The user stylesheet is specified by using the option `-p custom.xsl`.

### Changing the XSL parameter values

The parameters can be stored in a user defined XSL stylesheet. An example of configuration stylesheet is given with this manual:

### Overriding some templates

You can directly put the overriding templates in your XSL stylesheet, but do not try to import the default dblatex stylesheets in it: it is automatically done by the tool. So, just focus on the template to override and dblatex will ensure that your definitions will get precedence over the dblatex ones.

You can of course split your templates in several files, and import each of them in the main user stylesheet by calling `xsl:import`.

Overriding templates

    <?xml version='1.0' encoding="iso-8859-1"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

    <!-- Let's import our own XSL to override the default behaviour. -->
    <xsl:import href="mystyle.xsl"/>

    <!-- Let's patch directly a template here -->
    <xsl:template match="article" mode="docinfo">
      <xsl:apply-imports/>
      <xsl:text>\let\mymacro=\DBKrelease</xsl:text>
    </xsl:template>

    </xsl:stylesheet>

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

Reused LaTeX style

### Package options

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

### Needed packages

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

### DocBook interface

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

## Latex post process script

Extra user actions can be processed on the latex file produced by the XSL stylesheets or on its temporary working files produced by the latex compilation.

For instance, in the documents I write the cover page must display the number of pages of the document, but written in full letters (e.g. 23 is written “twenty three”). The latex post process script is then helpfull, and in this particular case it patches the .aux file.

The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool.

### Post latex compilations

The latex compilations done once the script is called depend on the return code of the script:

- When the return code is 0, `dblatex` continues the compilation as many times as necessary.

- When the return code is 1, no more compilation is done by dblatex. This case is useful if the script needs to control precisely the number of compilation to apply. It is up to the script to perform the expected compilations.

  To do so, the script can retrieve in the `LATEX` environment variable the actual compiler used by `dblatex`.

- When the return code is another value, an error is raised to signal a failed post process script execution.

### Post processing with a Python Plugin

You can use a python plugin instead of a script by prefixing the plugin name with the string `"plugin:"`. When using a plugin you must not put the python suffix in the plugin name. If the plugin is in one of the Python system directories, or in the current directory where you call dblatex, or in one of the directories of the `PYTHONPATH` environment variable, you don't need to specify a directory location. Otherwise put the plugin directory path before the plugin name.

Here are several plugin call examples:

    # The texpost.py module is in one of the python paths
    dblatex -r plugin:texpost file.xml

    # The texpost.py module location is specified with an absolute path
    dblatex -r plugin:/path/to/texpost file.xml

    # The texpost.py module is specified through a relative path from current dir
    dblatex -r plugin:relative/path/from/current/dir/texpost file.xml

The plugin must contain a `main` entry point. `Dblatex` will pass the following parameters to the entry point: latex_file to specify the latex file to post process, and stdout to specify the output stream to use to be consistent with the dblatex verbosity.

Texpost Python Plugin Example

    import sys
    import os

    def main(latex_file, stdout):
        """
        Texpost Plugin Entry point
        """
        # Let's find out the backend used
        tex_engine = os.environ["LATEX"]

        # Let's log something
        print >>stdout, "Plugin called on '%s' file" % (latex_file)

        # Open the latex file and parse it
        texfile = open(latex_file)
        ...

        # Now decide if a new compilation must occur
        if has_changed:
          sys.exit(0)
        else:
          sys.exit(1)

## Dblatex Configuration File

A master configuration file, also called a specification file, can be used to list all the customizations and options to apply. Such a file is passed by using the option `-S config_file`.

### Configuration File Format

The format of the file is the following:

- Every comment starts with a “#”, and is ignored.

- The file must contain one parameter by line.

- The format of a parameter is the following:

      <keyword>: <value>

- Every parameter is mapped to an option that can be passed to `dblatex`.

- An unknown parameter is silently ignored (the whole line is dropped).

- The parameters defining a path (a file or a directory) can take absolute or relative paths. A relative path must be defined from the specification file itself. For instance, a specification file under `/the/spec/directory/` with a parameter describing the file `../where/this/file/is/myfile` points to `/the/spec/where/this/file/is/myfile`.

The following table lists the supported parameters and the corresponding command line option.

Here is the specification file used for this manual.

User Manual Configuration File

### Configuration Paths

By default `dblatex` tries to find the configuration files in the following paths, in respect of the order:

1. The current directory

2. `$HOME/.dblatex`

3. `/etc/dblatex`

4. The dblatex package configuration directories.

You can add some extra paths where to look for by setting the `DBLATEX_CONFIG_FILES` environment variable. The paths are separated by ":" in Unix like systems, and by ";" on Windows. These paths are used only when nothing is found in the default paths.

## Customization Precedence

All the customization queries are translated to the corresponding command line options. Thus, using several customization methods can be unconsistent because each of them override the same option with another value.

For instance, you can specify the use of a specification file in which it is said to use a latex style (parameter TexStyle) and explicitely use the `--texstyle` command line option. So, what is the behaviour?

The options order is the following:

- If a specification file is used (`-S` option), the options are set to the specification file parameters.

- The options explicitely passed override the specification file setting, whatever is the position of the options (i.e. before or after the `-S` option).

- If an option is passed several times, this is the last occurence that is used.

Customization Precedence

Let's consider the specification file containing the following parameters:

    XslParam: file3.xsl
    Options: -b pdftex
    TexStyle: mystyle1

And now the command line:

    dblatex -b dvips -p file1.xsl -p file2.xsl -S file.specs -s mystyle2 mydoc.xml

The setting used is the following:

- “-b dvips” overrides “-b pdftex” set by the spec file.

- “-p file2.xsl” overrides “-p file1.xsl” since it is defined after, and overrides “file3.xsl” set by the spec file.

- “-s mystyle2” override “mystyle1” set by the spec file.