Output Formatting Style

How it works
Adding a New Formatting Style

The output rendering done by dblatex can be widely customized like explained in Chapter 4, Customization. By default several rendering styles are provided, that one can choose by using the option -T (see Example 3.1, “Choosing the DB2LaTeX style”). The available styles are:

native

The rendering uses the default LaTeX stylesheets. It is the style used by default if dblatex has been configured without using the option --style.

simple

The rendering is very close to original latex rendering. The wrapper around the default latex packages is very thin.

db2latex

The rendering tries to be as close as possible to the DB2LaTeX formatting.

Example 3.1. Choosing the DB2LaTeX style

dblatex -T db2latex file.xml

How it works

The rendering style stuff is under the latex/ directory. You can see the XSL stylesheets under xsl/ as the way to produce latex with as little as possible docbook specific things (even if a large amount of latex packages are used to do the work). Then, it's up to LaTeX stylesheets to format the document as you wish.

The organization under latex/ is as follow:

contrib

Contains the non-default available LaTeX stylesheets (simple and db2latex).

graphics

Default graphics used in the admonitions (e.g. warning). These graphics are used by the default output formatting.

scripts

Scripts used to compile with latex or pdflatex.

specs

Contains all the configuration files describing the available styles. A specification file must have the extension .specs, .conf, or .xml to be detected as a style description, and its basename is the name of the style. For example the style db2latex is described by the configuration file db2latex.xml.

When dblatex is executed with no parameter, the usage is displayed. In particular, the list of the available styles is given, like this:

$ dblatex
dblatex [options] file.{sgml|xml}
Options:
-t {pdf|ps|dvi|tex|xml}: output format
...
-T style               : available latex styles (db2latex, native, simple)

The list is built by scanning the specs files found under specs/. The spec file syntax is described in the section called “Dblatex Configuration File”.

style

Default LaTeX stylesheets.

Adding a New Formatting Style

To add a new formatting style, do the following steps:

  1. Let's create the style directores that will contain all the specific data. We choose to put them under the default dblatex user configuration directory.

    $ mkdir -p $HOME/.dblatex/mystyle/latex
    $ mkdir -p $HOME/.dblatex/mystyle/xsl
    

    Note that you could choose another configuration directory (see the section called “Configuration Paths” for more details).

  2. Create the latex stylesheets you need. It must define the expected DocBook interface and include some core definitions from the default latex stylesheets (cf. the section called “Customized LaTeX style”). Create also your XSL stylesheet if necessary.

  3. Put these files under the appropriate directories:

    $ mv mytexstyle.sty $HOME/.dblatex/mystyle/latex/.
    $ mv param.xsl $HOME/.dblatex/mystyle/xsl/.
    
  4. Create a configuration file under the directory $HOME/.dblatex. The configuration file must point to the new latex stylesheet, and give the specific parameters. Example:

    $ cat $HOME/.dblatex/mystyle.conf
    <?xml version="1.0" encoding="utf-8"?>
    <!-- =======================================================
         Dblatex config file for my new style.
         Note that the directories are relative to mystyle.conf
         ======================================================= -->
    <config xmlns="http://dblatex.sourceforge.net/config">
      <latex>
        <texinputs>mystyle/latex//</texinputs>
        <texstyle use="mytexstyle"/>
      </latex>
      <xslt>
        <stylesheet fileref="mystyle/xsl/param.xsl"/>
      </xslt>
      <options>-f fig</options>
    </config>
    
  5. That's it. Try to compile your document with your style, and check the output.

    $ dblatex -T mystyle file.xml