9 Customizing Layout of the Output Formats #

If you use the default DocBook layout and want to adjust individual parameters, add the --param "KEY=VALUE" or the --stringparam "KEY=VALUE" option. Both options can be added multiple times, and they work with the following subcommands that specify the output formats:

The options pass on values for XSLT parameters directly to the XSLT processor, which is useful to temporarily overwrite style sheet parameters such as margins.

Note: XSLTPARAM And --param/--stringparam

Use --param "KEY=VALUE" or --stringparam "KEY=VALUE" to set XSLT parameters on the command line.

However, if you want to specify your settings in the DC file instead, the respective parameter is named XSLTPARAM.

For larger or more complex modifications, such as adjustments of the title page layout, for example, it is advisable to create your own set of stylesheets instead.

For a list of XSLT parameters to modify, refer to one of the following references at http://docbook.sourceforge.net/release/xsl/current/doc/index.html:

tux:~> daps -d   PATH_TO_DC_FILE html \
--param1 "variablelist.as.table2=0"3 \
--param "variablelist.term.break.after=1" \
--stringparam1 "paper.type=A4"

XSLTPARAM="--stringparam PARAM_NAME=VALUE --param PARAM_NAME=VALUE"

XSLTPARAM="--stringparam PARAM_NAME=VALUE"
XSLTPARAM+="$XSLTPARAM --param PARAM_NAME=VALUE"

You can set parameters in /etc/daps/config or ~/.config/daps/dapsrc using the TXT_PARAMS parameter. Alternatively, set them from the command line, using the --param/--stringparam options. By default, the stylesheets specified with the STYLEROOT parameter or the --styleroot option are used for generating ASCII text output.

However, if you want to ignore any STYLEROOT definitions, set TXT_IGNORE_STYLEROOT="yes" in /etc/daps/config or ~/.config/daps/dapsrc or use the --ignore-styleroot option on the command line:

tux:~> daps -d PATH_TO_DC_FILE text --ignore-styleroot

This section describe how you can use customs stylesheets. There are many reasons why it would be preferable to create your own customization layer. Perhaps you want to change the layout or style of your project, change the behaviour how an element is processed or want to create a corporate style.

Important

The reader should be aware of that some knowledge about XSLT is needed. Basic customizations like parameter changes can be done by simple adding a line with:

<xsl:param name="PARAMETER_NAME" select="VALUE"/>

The available parameters are format dependent and are listed in the "XSL Stylesheets Reference Documentation" (http://docbook.sourceforge.net/release/xsl/current/doc/param.html).

Best practice is to store the stylesheets in a xslt directory as the top-level directory with different subdirectories for all formats. Depending on which formats are supported, this top-level directory could be integrated into your project directory like this:

        YOUR_DOC_DIR/
         |
         +-- DC-files
         +-- xml/
              +--- your XML files...
         +-- xslt/
              +-- fo/
                   +-- docbook.xsl
              +-- html/
                   +-- docbook.xsl
                   +-- chunk.xsl
               +-- [additional formats, supported by DB XSL]
                   +-- docbook.xsl

Finaly include the STYLEROOT variable in your DC files, pointing to the xslt directory.

Note

It is recomended to also set the FALLBACK_STYLEROOT variable which is used in case the custom stylesheets defined with STYLEROOT cannot be accessed.

In the following procedure we will create the directory stucture for customizations of the HTML output. For other formats, replace "html" with the approperiate name, e.g.: "fo".

Useful tips and tricks on using DocBook and the DocBook stylesheets can be found in The DoCookBook—Recipes for DocBook Developers and Writers, available at http://doccookbook.sourceforge.net/ and in DocBook XSL Stylesheets: Reference Documentation available at http://docbook.sourceforge.net/release/xsl/current/doc/index.html.