<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
 <chapter id="sec-custom">
  <title>Customization</title>
 <para>
  The transformation process (and thus the output rendering) can be heavily customized by:
 </para>
 <itemizedlist>
  <listitem>
  <para>
  using some <link linkend="sec-param">configuration parameters</link> either in
  a <link linkend="sec-param-stylesheet">configuration stylesheet</link> or directly
  from the <link linkend="sec-param-value">command line</link>,
  </para>
 </listitem>
  <listitem>
  <para>
  using some <link linkend="sec-custom-stylesheet">customized stylesheets</link>,
  </para>
 </listitem>
  <listitem>
  <para>
  using a <link linkend="sec-custom-latex">customized LaTeX style package</link>.
  </para>
 </listitem>
  <listitem>
  <para>
  using a <link linkend="sec-texpost">LaTeX post process script</link>.
  </para>
 </listitem>
 </itemizedlist>
 <para>
  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. <xref linkend="sec-specs"/>) to create a new tool dedicated to your needs.
 </para>
<section id="sec-param">
   <title>Using XSL Parameters</title>
  <para>
   The PDF rendering can be customised by using some XSL configuration
   parameters.
   <xref linkend="sec-params"/> contains the reference documentation of
   the available user-configurable parameters.
  </para>
</section>

<section id="sec-param-value"><title>Setting Command line Parameters</title>
  <para>You can set some XSL parameters directly from the command
  line without creating a configuration parameter stylesheet, with the
  <option>-P <replaceable>parameter=value</replaceable></option> option.</para>
  <para>The following example set the latex.hyperparam parameter value:
   <programlisting>
<![CDATA[  dblatex -P latex.hyperparam=colorlinks,linkcolor=blue myfile.xml
]]></programlisting>
  </para>
</section>

<section>
<title>XSL User Stylesheet</title>
  <para>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
  <option>-p <replaceable>custom.xsl</replaceable></option>.</para>

<section id="sec-param-stylesheet">
<title>Changing the XSL parameter values</title>
  <para>
   The parameters can be stored in a user defined XSL stylesheet. An example of
   configuration stylesheet is given with this manual:
  </para>
  <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
                   parse="text" href="../manual.xsl"/></programlisting>
  </section>
  <section id="sec-custom-stylesheet">
   <title>Overriding some templates</title>
  <para>
   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.
  </para>
  <para>
  You can of course split your templates in several files, and import each of
  them in the main user stylesheet by calling <literal>xsl:import</literal>.
  </para>
<example><title>Overriding templates</title>
  <programlisting>
<![CDATA[<?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>
]]>  </programlisting>
</example>
  </section>
  </section>
  <section id="sec-custom-latex">
   <title>Customized LaTeX style</title>
  <para>
   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:
  </para>
  <itemizedlist>
   <listitem>
   <para>
   The LaTeX style package preamble must support all the options that the XSL stylesheets can pass to the package.
   </para>
  </listitem>
   <listitem>
   <para>
   Some packages must be used to make all the thing work.
   </para>
  </listitem>
   <listitem>
   <para>
   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.
   </para>
  </listitem>
  </itemizedlist>
  <para>
   The latex style file to use is specified by using the option <option>--texstyle <replaceable>latex_style</replaceable></option>. An example of a simple LaTeX DocBook style is provided in the package.
  </para>
  <para>
   The <option>--texstyle <replaceable>latex_style</replaceable></option> option
   accepts a package name (no path and no <filename>.sty</filename> extension)
   or a full style file path. If a full path is used,
   the filename must ends with <filename>.sty</filename>.
   </para>
   <programlisting>
# 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
</programlisting>
<section><title>Reusing an existing LaTeX style</title>
<para>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.</para>
<para>Here is an example of a style package reusing the default docbook
style:</para>
<example><title>Reused LaTeX style</title>
<programlisting>
<xi:include href="mystyle.sty" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text" encoding="ISO-8859-1"/>
</programlisting>
</example>
</section>
   <section>
    <title>Package options</title>
   <para>A compliant LaTeX style package supports the following options. The options are
   provided by the XSL stylesheets according to the document attributes.</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="styoption.xml"/>
   </section>
   <section>
    <title>Needed packages</title>
   <para>A LaTeX style package must at least include the following packages.</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stypackage.xml"/>
   </section>
   <section>
    <title>DocBook interface</title>
   <para>
    All the latex commands beginning with DBK are related to elements under <sgmltag>bookinfo</sgmltag> or <sgmltag>articleinfo</sgmltag>.
   </para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stycommand.xml"/>
   </section>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stydebug.xml"/>
  </section>
  <section id="sec-texpost">
   <title>Latex post process script</title>
  <para>
   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. 
  </para>
  <para>
   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 &ldquo;twenty three&rdquo;). The latex post process script is then helpfull, and in this particular case it patches the .aux file.
  </para>
  <para>
   The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool.
  </para>
  <section><title>Post latex compilations</title>
  <para>
   The latex compilations done once the script is called depend on the return code
   of the script:
  <itemizedlist>
   <listitem>
   <para>
   When the return code is 0, <command>dblatex</command> continues the
   compilation as many times as necessary.
   </para>
  </listitem>
   <listitem>
   <para>
   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.</para>
   <para>To do so, the script can retrieve in the <envar>LATEX</envar> environment
   variable the actual compiler used by <command>dblatex</command>.
   </para>
  </listitem>
   <listitem>
   <para>
   When the return code is another value, an error is raised to signal
   a failed post process script execution.
   </para>
  </listitem>
  </itemizedlist>
  </para>
  </section>
  </section>
  <section id="sec-specs">
   <title>Dblatex Configuration File</title>
  <para>
   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 <option>-S <replaceable>config_file</replaceable></option>.
  </para>
  <section><title>Configuration File Format</title>
  <para>
   The format of the file is the following:
  </para>
  <itemizedlist>
   <listitem>
   <para>
   Every comment starts with a &ldquo;&num;&rdquo;, and is ignored.
   </para>
  </listitem>
   <listitem>
   <para>
   The file must contain one parameter by line.
   </para>
  </listitem>
   <listitem>
   <para>
   The format of a parameter is the following:
   </para>
   <programlisting>
<![CDATA[<keyword>: <value>
]]>   </programlisting>
  </listitem>
   <listitem>
   <para>
   Every parameter is mapped to an option that can be passed to <command>dblatex</command>.
   </para>
  </listitem>
   <listitem>
   <para>
   An unknown parameter is silently ignored (the whole line is dropped).
   </para>
  </listitem>
   <listitem>
   <para>
   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 <filename>/the/spec/directory/</filename> with a parameter describing the file <filename>../where/this/file/is/myfile</filename> points to <filename>/the/spec/where/this/file/is/myfile</filename>.
   </para>
  </listitem>
  </itemizedlist>
  <para>
   The following table lists the supported parameters and the corresponding command line option.
  </para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="specparam.xml"/>
  <para>
   Here is the specification file used for this manual.
  </para>
<example><title>User Manual Configuration File</title>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
                 parse="text" href="../manual.specs"/></programlisting>
</example>
  </section>
  <section id="sec-conf-path"><title>Configuration Paths</title>
  <para>By default <command>dblatex</command> tries to find the configuration files
  in the following paths, in respect of the order:</para>
  <orderedlist>
  <listitem><para>The current directory</para></listitem>
  <listitem><para><filename>$HOME/.dblatex</filename></para></listitem>
  <listitem><para><filename>/etc/dblatex</filename></para></listitem>
  <listitem><para>The dblatex package configuration directories.</para></listitem>
  </orderedlist>
  <para>You can add some extra paths where to look for by setting the
  <envar>DBLATEX_CONFIG_FILES</envar> 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.</para>
  </section>
  </section>
  <section>
   <title>Customization Precedence</title>
  <para>
   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. 
  </para>
  <para>
   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 <option>--texstyle</option> command line option. So, what is the behaviour?
  </para>
  <para>
   The options order is the following:
  </para>
  <itemizedlist>
   <listitem>
   <para>
   If a specification file is used (<option>-S</option> option), the options are set to the specification file parameters.
   </para>
  </listitem>
   <listitem>
   <para>
   The options explicitely passed override the specification file setting, whatever is the position of the options (i.e. before or after the <option>-S</option> option).
   </para>
  </listitem>
   <listitem>
   <para>
   If an option is passed several times, this is the last occurence that is used.
   </para>
  </listitem>
  </itemizedlist>
<example><title>Customization Precedence</title>
  <para>
   Let's consider the specification file containing the following parameters:
  </para>
  <programlisting>
<![CDATA[XslParam: file3.xsl
]]><![CDATA[Options: -b pdftex 
]]><![CDATA[TexStyle: mystyle1
]]>  </programlisting>
  <para>
   And now the command line:
  </para>
  <programlisting>
<![CDATA[dblatex -b dvips -p file1.xsl -p file2.xsl -S file.specs -s mystyle2 mydoc.xml
]]>  </programlisting>
  <para>
   The setting used is the following:
  </para>
  <itemizedlist>
   <listitem>
   <para>
   &ldquo;-b dvips&rdquo; overrides &ldquo;-b pdftex&rdquo; set by the spec file.
   </para>
  </listitem>
   <listitem>
   <para>
   &ldquo;-p file2.xsl&rdquo; overrides &ldquo;-p file1.xsl&rdquo; since it is defined after, and overrides &ldquo;file3.xsl&rdquo; set by the spec file. 
   </para>
  </listitem>
   <listitem>
   <para>
   &ldquo;-s mystyle2&rdquo; override &ldquo;mystyle1&rdquo; set by the spec file.
   </para>
  </listitem>
  </itemizedlist>
</example>
  </section>
 </chapter>