1
<?xml version="1.0" encoding="iso-8859-1"?>
1
<?xml version="1.0" encoding="ISO-8859-1"?>
2
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4
4
<chapter id="sec-custom">
5
<title>Customization</title>
9
7
The transformation process (and thus the output rendering) can be heavily customized by:
14
using a configuration stylesheet,
19
using customized stylesheets,
24
using a customized LaTeX style package.
12
using some <link linkend="sec-param">configuration parameters</link> either in
13
a <link linkend="sec-param-stylesheet">configuration stylesheet</link> or directly
14
from the <link linkend="sec-param-value">command line</link>,
19
using some <link linkend="sec-custom-stylesheet">customized stylesheets</link>,
24
using a <link linkend="sec-custom-latex">customized LaTeX style package</link>.
34
34
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.
36
<sect1 id="sec-param">
38
Configuration Parameter Stylesheet
36
<section id="sec-param">
37
<title>XSL Parameters</title>
41
The PDF rendering can be customised by using an XSL configuration stylesheet. The configuration file is specified by using the option <option>-p <replaceable>custom.xsl</replaceable></option>. The available configuration parameters are the following:
39
The PDF rendering can be customised by using some XSL configuration parameters.
40
The available configuration parameters are the following:
43
42
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="param.xml"/>
44
<sect2 id="sec-defaultscale">
43
<section id="sec-defaultscale">
45
44
<title>imagedata.default.scale</title>
46
45
<para>Default scale to apply to every <sgmltag>imagedata</sgmltag> that does not
47
46
contain any scaling attribute.</para>
83
80
]]><![CDATA[</xsl:stylesheet>
84
81
]]> </programlisting>
88
<sect1 id="sec-param-value"><title>Setting Parameter values</title>
89
<para>It is possible to set some XSL parameter values directly from the command
90
line without creating a configuration parameter stylesheet, by using the
86
<section id="sec-param-value"><title>Setting Command line Parameters</title>
87
<para>You can set some XSL parameters directly from the command
88
line without creating a configuration parameter stylesheet, with the
91
89
<option>-P <replaceable>parameter=value</replaceable></option> option.</para>
92
90
<para>The following example set the latex.hyperparam parameter value:
94
92
<![CDATA[ dblatex -P latex.hyperparam=colorlinks,linkcolor=blue myfile.xml
95
93
]]></programlisting>
100
Customized stylesheets
103
If one needs to change some of the translations done by the XSL stylesheets, it is possible to provide user stylesheets to override the templates. To do this, write the stylesheets (e.g. mystyle.xsl) and include them in the configuration file such as shown by the following example.
105
<example><title>Using a customized stylesheet in a configuration file</title>
98
<title>XSL User Stylesheet</title>
99
<para>You can provide your own XSL stylesheet to set some of the XSL parameters,
100
and/or to override some of the dblatex XSL templates. The user stylesheet is
101
specified by using the option
102
<option>-p <replaceable>custom.xsl</replaceable></option>.</para>
104
<section id="sec-param-stylesheet">
105
<title>Changing the XSL parameter values</title>
107
The parameters can be stored in a user defined XSL stylesheet. An example of
108
configuration stylesheet is given with this manual:
110
<programlisting><textobject><textdata
111
fileref="myparam.xsl"/></textobject></programlisting>
113
<section id="sec-custom-stylesheet">
114
<title>Overriding some templates</title>
116
You can directly put the overriding templates in your XSL stylesheet, but do not
117
try to import the default dblatex stylesheets in it: it is automatically done by
118
the tool. So, just focus on the template to override and dblatex will ensure
119
that your definitions will get precedence over the dblatex ones.
122
You can of course split your templates in several files, and import each of
123
them in the main user stylesheet by calling <literal>xsl:import</literal>.
125
<example><title>Overriding templates</title>
107
127
<![CDATA[<?xml version='1.0' encoding="iso-8859-1"?>
108
]]><![CDATA[<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
110
]]><![CDATA[<!-- Let's import our own XSL to override the default behaviour.
112
]]><![CDATA[<xsl:import href="mystyle.xsl"/>
114
]]><![CDATA[</xsl:stylesheet>
128
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
130
<!-- Let's import our own XSL to override the default behaviour. -->
131
<xsl:import href="mystyle.xsl"/>
133
<!-- Let's patch directly a template here -->
134
<xsl:template match="article" mode="docinfo">
136
<xsl:text>\let\mymacro=\DBKrelease</xsl:text>
115
140
]]> </programlisting>
118
<sect1 id="sec-custom-latex">
120
Customized LaTeX style
144
<section id="sec-custom-latex">
145
<title>Customized LaTeX style</title>
123
147
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:
143
The latex style file to use is specified by using the option <option>--style <replaceable>latex_style</replaceable></option>. An example of a simple LaTeX DocBook style is provided in the package.
167
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.
170
The <option>--texstyle <replaceable>latex_style</replaceable></option> option
171
accepts a package name (no path and no <filename>.sty</filename> extension) or a
172
full style file path. If a full path is used,
173
the filename must ends with <filename>.sty</filename>.
176
# Give a package name and assume its path is already in TEXINPUTS
177
dblatex --texstyle=mystyle file.xml
179
# Give the full package path. The TEXINPUTS is then updated by dblatex
180
dblatex --texstyle=./mystyle.sty file.xml
182
<section><title>Reusing an existing LaTeX style</title>
183
<para>You can either create your latex style from scratch, in respect of the
184
interfaces described in the following sections, or you can simply reuse an
185
already existing style and override what you want. The latter method is easier
186
for small things to change.</para>
187
<para>Here is an example of a style package reusing the default docbook
189
<example><title>Reused LaTeX style</title>
190
<programlisting><textobject><textdata fileref="mystyle.sty"/></textobject>
195
<title>Package options</title>
149
196
<para>A compliant LaTeX style package supports the following options. The options are
150
197
provided by the XSL stylesheets according to the document attributes.</para>
151
198
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="styoption.xml"/>
201
<title>Needed packages</title>
157
202
<para>A LaTeX style package must at least include the following packages.</para>
158
203
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stypackage.xml"/>
206
<title>DocBook interface</title>
165
208
All the latex commands beginning with DBK are related to elements under <sgmltag>bookinfo</sgmltag> or <sgmltag>articleinfo</sgmltag>.
167
210
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stycommand.xml"/>
169
212
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stydebug.xml"/>
173
Latex post process script
214
<section id="sec-texpost">
215
<title>Latex post process script</title>
176
217
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.
182
223
The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool.
185
<sect1 id="sec-specs">
190
A master configuration file, also called a specification file, can be defined to list all the customizations and options to apply. Such a file is passed by using the option <option>-S <replaceable>specs</replaceable></option>.
225
<section><title>Post latex compilations</title>
227
The latex compilations done once the script is called depend on the return code
232
When the return code is 0, <command>dblatex</command> continues the
233
compilation as many times as necessary.
238
When the return code is 1, no more compilation is done by dblatex.
240
if the script needs to control precisely the number of compilation to apply.
241
It is up to the script to perform the expected compilations.</para>
242
<para>To do so, the script can retrieve in the <envar>LATEX</envar> environment
243
variable the actual compiler used by <command>dblatex</command>.
248
When the return code is another value, an error is raised to signal
249
a failed post process script execution.
256
<section id="sec-specs">
257
<title>Dblatex Configuration File</title>
259
A master configuration file, also called a specification file, can be used to list
260
all the customizations and options to apply. Such a file is passed by using the
261
option <option>-S <replaceable>config_file</replaceable></option>.
263
<section><title>Configuration File Format</title>
193
265
The format of the file is the following:
235
307
Here is the specification file used for this manual.
237
<example><title>Specification file example</title>
309
<example><title>User Manual Configuration File</title>
238
310
<programlisting><textobject><textdata fileref="manual.specs"/></textobject>
239
311
</programlisting>
314
<section id="sec-conf-path"><title>Configuration Paths</title>
315
<para>By default <command>dblatex</command> tries to find the configuration files
316
in the following paths, in respect of the order:</para>
318
<listitem><para>The current directory</para></listitem>
319
<listitem><para><filename>$HOME/.dblatex</filename></para></listitem>
320
<listitem><para><filename>/etc/dblatex</filename></para></listitem>
321
<listitem><para>The dblatex package configuration directories.</para></listitem>
323
<para>You can add some extra paths where to look for by setting the
324
<envar>DBLATEX_CONFIG_FILES</envar> environment variable. The paths are
325
separated by ":" in Unix like systems, and by ";" on Windows. These paths are used
326
only when nothing is found in the default paths.</para>
330
<title>Customization Precedence</title>
247
332
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.
250
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>--style</option> command line option. So, what is the behaviour?
335
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?
253
338
The options order is the following:
added
removed
docs/custom/custom.xml
