Dblatex Configuration File
Prev | Chapter 4. Customization | Next

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

### XML Configuration File Format

You should use the XML format to configure dblatex. It contains more features than the text format used up to the 0.3.7 release that is now deprecated. The principle remains the same, that is, most of the configuration parameters correspond to a command line option.

Here is a full example of a configuration file. In the next sections the meaning and use of the configuration tags are detailed.

    <?xml version="1.0" encoding="utf-8"?>
    <!-- ======================================================= -->
    <!-- Dblatex Configuration example for building a book       -->
    <!-- ======================================================= -->
    <config xmlns="http://dblatex.sourceforge.net/config" version="1.0">
      <latex>
        <backend use="xetex"/>
        <texstyle use="dbsimple"/>
        <texpost fileref="dblatex-postprocess"/>
        <indexstyle fileref="../myindexstyle.ist"/>
        <texinputs>../mystyledir:/etc/texmf/userfont</texinputs>
      </latex>
      <xslt>
        <stylesheet fileref="user_param.xsl"/>
        <stylesheet fileref="xetex_param.xsl"/>
        <stylesheet fileref="pdf.xsl"/>
      </xslt>
      <imagedata>
        <converter src="svg" dst="*" docformat="pdf">
          <command>
            inkscape -z -D --export-dpi=600 --export-%(dst)s=%(output)s %(input)s
          </command>
        </converter>
      </imagedata>
      <options>-X -V</options>
    </config>

Another example, much simpler, is the configuration file used for this manual.

Example 4.5. User Manual Configuration File

    <?xml version="1.0" ?>
    <!--
      ====================================================================
      Configuration file for dblatex documentation (manual, release notes)
      ====================================================================
    -->
    <config xmlns="http://dblatex.sourceforge.net/config">
      <latex>
        <texinputs>../latex//</texinputs>
        <texstyle use="docbook"/>
        <backend use="pdftex"/>
      </latex>
      <xslt>
        <stylesheet fileref="manual.xsl"/>
      </xslt>
    </config>

The following sections detail the meaning of each tag. Note that dblatex provides some schema that you can use to validate your configuration file.

#### `<config>`

It is the root element of a configuration file. A valid configuration file must have a `config` root element.

Attributes:

xmlns

  The namespace to use for a dblatex configuration file is: `http://dblatex.sourceforge.net/config`.

The following elements occur in `config`: latex, xslt, imagedata, options.

#### `<latex>`

The latex element contains the configuration data related to the latex processing.

Attributes: none

The following elements occur in `latex`:

`backend`

  It defines the latex engine to use, like the option `--backend` does. The backend name is specified through the `use` attribute.

`texstyle`

  It defines the docbook latex style to use, like the option `--texstyle` does. The latex package is specified through the `use` attribute.

`texpost`

  It defines the latex post-processing script to use, like the option `--texpost` does. The script name is specified through the `use` attribute or the `fileref` attribute.

`indexstyle`

  It defines index style file (.ist) to use, like the option `--indexstyle` does. The filename is specified through the `fileref` attribute.

`texinputs`

  The element text defines the extra paths to add to TEXINPUTS, like the option `--texinputs` does.

`bibinputs`

  The element text defines the lookup paths of BIBINPUTS, like you would do by successive use of the option `--bib-path`.

`bstinputs`

  The element text defines the lookup paths of BSTINPUTS, like you would do by successive use of the option `--bst-path`.

#### `<xslt>`

The xslt element contains the configuration data related to the XSL processing.

Attributes: none

The following elements occur in `xslt`:

`stylesheet`

  It defines a user stylesheet to use, like the option `--xsl-user` does. The stylesheet name is specified through the `fileref` attribute. If several `stylesheet` elements are set, the precedence is the same like using the option `--xsl-user` several times.

`engine`

  See engine.

#### `<engine>`

It defines the XSLT processor to use; it can be either a predefined engine, or a user-defined command to run.

When the attribute `use` is used, it works like the option `--xslt`. The engine name is specified through the `use` attribute.

When the element contains the `command` or `commandchain` child element it defines the command(s) to run to perform the XSLT processing. The core keywords defined in command apply. The additional keywords of an XSLT engine command are the following:

`%(xmlfile)s`

  Replaced by the XML source file to process.

`%(stylesheet)s`

  Replaced by the stylesheet to use to process the XML file `xmlfile`.

`%(param_list)s`

  Replaced by the list of the XSL parameters to set. The parameter pair formatting (the parameter name and its value) is specified through the `param-format` attribute given to the `engine` element.

Attributes:

param-format

  This attribute is mandatory when the engine is specified through a `command`. It tells how a parameter name and value pair shall be formatted when added to the XSLT engine command. The formatting is given by a string containing the keywords replaced by the name or value of the parameter to set:

  `%(param_name)s`

    Replaced by the name of the parameter to set.

  `%(param_value)s`

    Replaced by the value to set to the parameter.

The following example re-writes with a user-defined command the Saxon engine with an additional `-T` option:

    <xslt>
      <engine param-format="%(param_name)s=%(param_value)s">
        <command>
        saxon-xslt -T -o %(output)s %(xmlfile)s
                                    %(stylesheet)s %(param_list)s</command>
      </engine>
    </xslt>

#### `<imagedata>`

The imagedata element contains the rules and commands to convert on the fly the images included in the docbook document.

Attributes: none

The following elements occur in `imagedata`:

`figpath`

  It defines a path where to find the images, like the option `--fig-path` does.

`figformat`

  It defines the default image format when no suffix is available to deduce the actual format, like `--fig-format` does.

`formatrule`

  It specifies in which format an image must be converted, depending on the context, given by some attributes:

  `docformat`

    The output document for which the rule applies. When not set the rule applies for any format

  `backend`

    The rule applies only when this backend is used

  `dst`

    When the conditions are met the image shall be converted to this format.

  The following example:

      <formatrule docformat="pdf" backend="xetex" dst="pdf"/>

  tells that when a PDF document is built with the xetex backend, the graphics not natively supported shall be converted to PDF.

`converter`

  It defines an image transformation rule. See converter for more details.

#### `<converter>`

The converter element defines a rule about how to convert on the fly an image in a docbook document to the corresponding image used in the built latex file. The goal is to have an image format compatible with the latex engine, whatever the original format is. Dblatex has a default set of rules, but one can overwrite or add some rules.

Attributes:

src

  Format of the original image referenced in the XML document. The converter only applies to the images matching this format.

dst

  Target format once converted. The converter only applies to the original images having the format `src` and that need to be converted to the format `dst`. `dst` can take the special value "`*`" meaning that the rule applies for all the possible target formats (e.g. eps, pdf, png).

docformat

  Specify for which document output format the converter applies. For example, if `docformat` is set to "pdf", it means that the converter applies only if the document output format is PDF. The converter will not apply if you want to build a PostScript or DVI document.

backend

  The converter applies only if it is this latex engine that is used. For example, it is usefull if you want to convert an image in a specific way only when xetex is used.

The following elements occur in `converter`:

`commandchain`

  List of the commands to run. A `commandchain` contains one or more `command` elements.

`command`

  command to execute to perform the conversion, or a part of the conversion if several commands are chained. See command.

#### `<command>`

The command element contains the arguments of the command to run. The arguments can contain some predefined keywords that are replaced by the actual values when the command is executed. The known core keywords are:

`%(src)s`

  Replaced by the `src` value (original image format).

`%(dst)s`

  Replaced by the `dst` value (target image format).

`%(input)s`

  Replaced by the input file required by the command. In the case of an image conversion, it is the filename of the original image to convert.

`%(output)s`

  Replaced by the name of the ouput file required by the command. In the case of an image conversion, it is the filename of the output image once converted.

Attributes:

input

  Standard input of the command to run. It can specify a file or it can specify to use the output of the preceding command if the keyword "PIPE" is used.

output

  Standard output of the command to run. It can specify a file or it can specify that the output shall be redirected to the next command if the keyword "PIPE" is used.

shell

  When set to "1" or "true", the command is run in a shell environment.

#### `<options>`

The options element lists the extra arguments to pass to dblatex.

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

Keyword | Value | Corresponding option | Description
--- | --- | --- | ---
TexInputs | Directories | --texinputs | Defines extra path to add to TEXINPUTS
TexStyle | Latex package name | --texstyle | Defines the LaTeX style package to use.
TexPost | Script file name | --texpost | Defines the LaTeX post process script to use.
XslParam | Parameter file name | -p | Defines the parameter file to use.
FigInputs | Directories | -I | Defines the extra figures path.
Options | Command line options | None | Lists command options to use by default when using the tool. The options specified by the parameter are directly passed to dblatex

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

Prev | Up | Next
Latex post process script | Home | Customization Precedence