1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 3"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> 4 <chapter id="sec-custom"> 5 <title>Customization</title> 6 <para> 7 The transformation process (and thus the output rendering) can be heavily customized by: 8 </para> 9 <itemizedlist> 10 <listitem> 11 <para> 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>, 15 </para> 16 </listitem> 17 <listitem> 18 <para>using <link linkend="sec-pi-usage">Processing Instructions</link> 19 to create some instructions very specific to dblatex,</para> 20 </listitem> 21 <listitem> 22 <para> 23 using some <link linkend="sec-custom-stylesheet">customized stylesheets</link>, 24 </para> 25 </listitem> 26 <listitem> 27 <para> 28 using a <link linkend="sec-custom-latex">customized LaTeX style package</link>. 29 </para> 30 </listitem> 31 <listitem> 32 <para> 33 using a <link linkend="sec-texpost">LaTeX post process script or plugin</link>. 34 </para> 35 </listitem> 36 </itemizedlist> 37 <para> 38 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. 39 </para> 40<section id="sec-param"> 41 <title>Using XSL Parameters</title> 42 <para> 43 The PDF rendering can be customised by using some XSL configuration 44 parameters. 45 <xref linkend="sec-params"/> contains the reference documentation of 46 the available user-configurable parameters. 47 </para> 48</section> 49 50<section id="sec-param-value"><title>Setting Command line Parameters</title> 51 <para>You can set some XSL parameters directly from the command 52 line without creating a configuration parameter stylesheet, with the 53 <option>-P <replaceable>parameter=value</replaceable></option> option.</para> 54 <para>The following example set the latex.hyperparam parameter value: 55 <programlisting> 56<![CDATA[ dblatex -P latex.hyperparam=colorlinks,linkcolor=blue myfile.xml 57]]></programlisting> 58 </para> 59</section> 60 61<section id="sec-pi-usage"> 62 <title>Using Processing Instructions</title> 63 64 <para>Dblatex has Processing Instructions (PI) which can modify the default 65 document formatting. Usually these instructions alter the 66 output formatting of specific DocBook elements, like table cells. 67</para> 68 69 <para>To alter formatting globally it is better to set an 70 appropriate <link linkend="sec-param">stylesheet 71 parameter</link>.</para> 72 73 <para>Processing instructions are written 74 <literal><?</literal><replaceable>name</replaceable> 75 <replaceable>content</replaceable> <literal>?></literal>. Most 76 often <replaceable>content</replaceable> will have the form of one or more 77 XML attributes with a value, as follows: 78 <literal><?</literal><replaceable>name</replaceable> 79 <replaceable>attribute</replaceable><literal>="</literal><replaceable>value</replaceable><literal>" ?></literal>.</para> 80 81 <para>The list of the available Processing Instructions are given in <xref 82 linkend="sec-pis"/>.</para> 83 84 <para>Here is an example of a PI used in a table:</para> 85 <example> 86 <title>Table width specified with a Processing Instruction</title> 87 <!-- 88 <xi:include href="../tables/table.xml" 89 xpointer="xpointer(id('lst-table-autowidth'))" 90 xmlns:xi="http://www.w3.org/2001/XInclude" /> 91 --> 92 <xi:include href="../tables/table.xml" 93 xpointer="lst-table-autowidth" 94 xmlns:xi="http://www.w3.org/2001/XInclude" /> 95 </example> 96 97</section> 98 99<section> 100<title>XSL User Stylesheet</title> 101 <para>You can provide your own XSL stylesheet to set some of the XSL parameters, 102 and/or to override some of the dblatex XSL templates. The user stylesheet is 103 specified by using the option 104 <option>-p <replaceable>custom.xsl</replaceable></option>.</para> 105 106<section id="sec-param-stylesheet"> 107<title>Changing the XSL parameter values</title> 108 <para> 109 The parameters can be stored in a user defined XSL stylesheet. An example of 110 configuration stylesheet is given with this manual: 111 </para> 112 <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 113 parse="text" href="../manual.xsl"/></programlisting> 114 </section> 115 <section id="sec-custom-stylesheet"> 116 <title>Overriding some templates</title> 117 <para> 118 You can directly put the overriding templates in your XSL stylesheet, but do not 119 try to import the default dblatex stylesheets in it: it is automatically done by 120 the tool. So, just focus on the template to override and dblatex will ensure 121 that your definitions will get precedence over the dblatex ones. 122 </para> 123 <para> 124 You can of course split your templates in several files, and import each of 125 them in the main user stylesheet by calling <literal>xsl:import</literal>. 126 </para> 127<example><title>Overriding templates</title> 128 <programlisting language="XML"> 129<![CDATA[<?xml version='1.0' encoding="iso-8859-1"?> 130<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> 131 132<!-- Let's import our own XSL to override the default behaviour. --> 133<xsl:import href="mystyle.xsl"/> 134 135<!-- Let's patch directly a template here --> 136<xsl:template match="article" mode="docinfo"> 137 <xsl:apply-imports/> 138 <xsl:text>\let\mymacro=\DBKrelease</xsl:text> 139</xsl:template> 140 141</xsl:stylesheet> 142]]> </programlisting> 143</example> 144 </section> 145 </section> 146 <section id="sec-custom-latex"> 147 <title>Customized LaTeX style</title> 148 <para> 149 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: 150 </para> 151 <itemizedlist> 152 <listitem> 153 <para> 154 The LaTeX style package preamble must support all the options that the XSL stylesheets can pass to the package. 155 </para> 156 </listitem> 157 <listitem> 158 <para> 159 Some packages must be used to make all the thing work. 160 </para> 161 </listitem> 162 <listitem> 163 <para> 164 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. 165 </para> 166 </listitem> 167 </itemizedlist> 168 <para> 169 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 </para> 171 <para> 172 The <option>--texstyle <replaceable>latex_style</replaceable></option> option 173 accepts a package name (no path and no <filename>.sty</filename> extension) 174 or a full style file path. If a full path is used, 175 the filename must ends with <filename>.sty</filename>. 176 </para> 177 <programlisting> 178# Give a package name and assume its path is already in TEXINPUTS 179dblatex --texstyle=mystyle file.xml 180 181# Give the full package path. The TEXINPUTS is then updated by dblatex 182dblatex --texstyle=./mystyle.sty file.xml 183</programlisting> 184<section><title>Reusing an existing LaTeX style</title> 185<para>You can either create your latex style from scratch, in respect of the 186interfaces described in the following sections, or you can simply reuse an 187already existing style and override what you want. The latter method is easier 188for small things to change.</para> 189<para>Here is an example of a style package reusing the default docbook 190style:</para> 191<example><title>Reused LaTeX style</title> 192<programlisting language="tex"> 193<xi:include href="mystyle.sty" xmlns:xi="http://www.w3.org/2001/XInclude" 194 parse="text" encoding="ISO-8859-1"/> 195</programlisting> 196</example> 197</section> 198 <section> 199 <title>Package options</title> 200 <para>A compliant LaTeX style package supports the following options. The options are 201 provided by the XSL stylesheets according to the document attributes.</para> 202<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="styoption.xml"/> 203 </section> 204 <section> 205 <title>Needed packages</title> 206 <para>A LaTeX style package must at least include the following packages.</para> 207<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stypackage.xml"/> 208 </section> 209 <section> 210 <title>DocBook interface</title> 211 <para> 212 All the latex commands beginning with DBK are related to elements under <sgmltag>bookinfo</sgmltag> or <sgmltag>articleinfo</sgmltag>. 213 </para> 214<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stycommand.xml"/> 215 </section> 216<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stydebug.xml"/> 217 </section> 218 <section id="sec-texpost"> 219 <title>Latex post process script</title> 220 <para> 221 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. 222 </para> 223 <para> 224 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 “twenty three”). The latex post process script is then helpfull, and in this particular case it patches the .aux file. 225 </para> 226 <para> 227 The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool. 228 </para> 229 <section><title>Post latex compilations</title> 230 <para> 231 The latex compilations done once the script is called depend on the return code 232 of the script: 233 <itemizedlist> 234 <listitem> 235 <para> 236 When the return code is 0, <command>dblatex</command> continues the 237 compilation as many times as necessary. 238 </para> 239 </listitem> 240 <listitem> 241 <para> 242 When the return code is 1, no more compilation is done by dblatex. 243 This case is useful 244 if the script needs to control precisely the number of compilation to apply. 245 It is up to the script to perform the expected compilations.</para> 246 <para>To do so, the script can retrieve in the <envar>LATEX</envar> environment 247 variable the actual compiler used by <command>dblatex</command>. 248 </para> 249 </listitem> 250 <listitem> 251 <para> 252 When the return code is another value, an error is raised to signal 253 a failed post process script execution. 254 </para> 255 </listitem> 256 </itemizedlist> 257 </para> 258 </section> 259 <section id="sec-texpost-py"><title>Post processing with a Python Plugin</title> 260 <para>You can use a python plugin instead of a script by prefixing 261 the plugin name with the string <literal>"plugin:"</literal>. When using a 262 plugin you must not put the python suffix in the plugin name. If the plugin 263 is in one of the Python system directories, or in the current directory where 264 you call dblatex, or in one of the directories of the 265 <envar>PYTHONPATH</envar> 266 environment variable, you don't need to specify a directory location. 267 Otherwise put the plugin directory path before the plugin name. 268 </para> 269 <para>Here are several plugin call examples: 270 <programlisting><![CDATA[# The texpost.py module is in one of the python paths 271dblatex -r plugin:texpost file.xml 272 273# The texpost.py module location is specified with an absolute path 274dblatex -r plugin:/path/to/texpost file.xml 275 276# The texpost.py module is specified through a relative path from current dir 277dblatex -r plugin:relative/path/from/current/dir/texpost file.xml 278]]></programlisting> 279 </para> 280 <para>The plugin must contain a <function>main</function> entry point. <command>Dblatex</command> will pass the following parameters to the entry point: <parameter>latex_file</parameter> to specify the latex file to post process, and <parameter>stdout</parameter> to specify the output stream to use to be consistent with the dblatex verbosity.</para> 281<example><title>Texpost Python Plugin Example</title> 282<programlisting language="python"><![CDATA[ 283import sys 284import os 285 286def main(latex_file, stdout): 287 """ 288 Texpost Plugin Entry point 289 """ 290 # Let's find out the backend used 291 tex_engine = os.environ["LATEX"] 292 293 # Let's log something 294 print >>stdout, "Plugin called on '%s' file" % (latex_file) 295 296 # Open the latex file and parse it 297 texfile = open(latex_file) 298 ... 299 300 # Now decide if a new compilation must occur 301 if has_changed: 302 sys.exit(0) 303 else: 304 sys.exit(1) 305 306]]></programlisting> 307</example> 308 309 </section> 310 </section> 311 <section id="sec-specs"> 312 <title>Dblatex Configuration File</title> 313 <para> 314 A configuration file, also called a specification file, can be used 315 to list all the customizations and options to apply. Such a file is passed 316 by using the 317 option <option>-S <replaceable>config_file</replaceable></option>. Several 318 configuration files can be specified if needed; it can be usefull to have a 319 default setup and additional setup for specific needs that override or 320 complete the default configuration. 321 </para> 322 <section id="sec-xml-config"> 323 <title>XML Configuration File Format</title> 324 <para> 325 You should use the XML format to configure dblatex. It contains more 326 features than the text format used up to the 0.3.7 release that is now 327 deprecated. The principle remains the same, that is, most of the 328 configuration parameters correspond to a command line option. 329 </para> 330 <para> 331 Here is a full example of a configuration file. In the next sections the 332 meaning and use of the configuration tags are detailed. 333 <programlisting language="XML"><xi:include 334 xmlns:xi="http://www.w3.org/2001/XInclude" href="dblatex.xconf" 335 parse="text"/></programlisting> 336 </para> 337 <para> 338 Another example, much simpler, is the configuration file used for 339 this manual. 340 </para> 341<example><title>User Manual Configuration File</title> 342<programlisting language="XML"><xi:include 343 xmlns:xi="http://www.w3.org/2001/XInclude" 344 parse="text" href="../manual.conf"/></programlisting> 345</example> 346 <para>The following sections detail the meaning of each tag. Note that 347 dblatex provides some schema that you can use to validate your configuration 348 file.</para> 349 350 <section id="sec-xconf-config" label="" xreflabel="config"> 351 <title><sgmltag><config></sgmltag></title> 352 <para>It is the root element of a configuration file. A valid configuration 353 file must have a <sgmltag>config</sgmltag> root element.</para> 354 <para>Attributes: 355 <variablelist> 356 <varlistentry> 357 <term>xmlns</term> 358 <listitem><para>The namespace to use for a dblatex configuration file is: 359 <literal>http://dblatex.sourceforge.net/config</literal>.</para></listitem> 360 </varlistentry> 361 </variablelist> 362 </para> 363 <para> 364 The following elements occur in <sgmltag>config</sgmltag>: 365 <xref linkend="sec-xconf-latex"/>, <xref linkend="sec-xconf-xslt"/>, 366 <xref linkend="sec-xconf-imagedata"/>, <xref linkend="sec-xconf-options"/>. 367 </para> 368 </section> 369 <section id="sec-xconf-latex" label="" xreflabel="latex"> 370 <title><sgmltag><latex></sgmltag></title> 371 <para>The latex element contains the configuration data related to the latex 372 processing.</para> 373 <para>Attributes: none</para> 374 <para> 375 The following elements occur in <sgmltag>latex</sgmltag>: 376 <variablelist> 377 <varlistentry> 378 <term><sgmltag>backend</sgmltag></term> 379 <listitem><para>It defines the latex engine to use, like the option 380 <option>--backend</option> does. The backend name is specified through the 381 <sgmltag>use</sgmltag> attribute.</para></listitem> 382 </varlistentry> 383 <varlistentry> 384 <term><sgmltag>texstyle</sgmltag></term> 385 <listitem><para>It defines the docbook latex style to use, like the option 386 <option>--texstyle</option> does. The latex package is specified through the 387 <sgmltag>use</sgmltag> attribute.</para></listitem> 388 </varlistentry> 389 <varlistentry> 390 <term><sgmltag>texpost</sgmltag></term> 391 <listitem><para>It defines the latex post-processing script to use, like the 392 option <option>--texpost</option> does. The script name is specified through the 393 <sgmltag>use</sgmltag> attribute or the <sgmltag>fileref</sgmltag> 394 attribute.</para></listitem> 395 </varlistentry> 396 <varlistentry> 397 <term><sgmltag>indexstyle</sgmltag></term> 398 <listitem><para>It defines index style file (.ist) to use, like the 399 option <option>--indexstyle</option> does. The filename is 400 specified through the <sgmltag>fileref</sgmltag> 401 attribute.</para></listitem> 402 </varlistentry> 403 <varlistentry> 404 <term><sgmltag>texinputs</sgmltag></term> 405 <listitem><para>The element text defines the extra paths to add to TEXINPUTS, 406 like the option <option>--texinputs</option> does.</para></listitem> 407 </varlistentry> 408 <varlistentry> 409 <term><sgmltag>bibinputs</sgmltag></term> 410 <listitem><para>The element text defines the lookup paths of BIBINPUTS, 411 like you would do by successive use of the option <option>--bib-path</option>. 412 </para></listitem> 413 </varlistentry> 414 <varlistentry> 415 <term><sgmltag>bstinputs</sgmltag></term> 416 <listitem><para>The element text defines the lookup paths of BSTINPUTS, 417 like you would do by successive use of the option <option>--bst-path</option>. 418 </para></listitem> 419 </varlistentry> 420 </variablelist> 421 </para> 422 </section> 423 <section id="sec-xconf-xslt" label="" xreflabel="xslt"> 424 <title><sgmltag><xslt></sgmltag></title> 425 <para>The xslt element contains the configuration data related to the XSL 426 processing.</para> 427 <para>Attributes: none</para> 428 <para> 429 The following elements occur in <sgmltag>xslt</sgmltag>: 430 <variablelist> 431 <varlistentry> 432 <term><sgmltag>stylesheet</sgmltag></term> 433 <listitem><para>It defines a user stylesheet to use, like the option 434 <option>--xsl-user</option> does. The stylesheet name is specified through the 435 <sgmltag>fileref</sgmltag> attribute. If several 436 <sgmltag>stylesheet</sgmltag> elements are set, the precedence is the same 437 like using the option <option>--xsl-user</option> several times.</para></listitem> 438 </varlistentry> 439 <varlistentry> 440 <term><sgmltag>engine</sgmltag></term> 441 <listitem><para>See <xref linkend="sec-xconf-engine"/>.</para></listitem> 442 </varlistentry> 443 </variablelist> 444 </para> 445 </section> 446 <section id="sec-xconf-engine" label="" xreflabel="engine"> 447 <title><sgmltag><engine></sgmltag></title> 448 <para>It defines the XSLT processor to use; it can be either a predefined 449 engine, or a user-defined command to run.</para> 450 <para>When the attribute 451 <sgmltag>use</sgmltag> is used, it works like the option 452 <option>--xslt</option>. The engine name is specified through the 453 <sgmltag>use</sgmltag> attribute.</para> 454 <para> 455 When the element contains the <sgmltag>command</sgmltag> or 456 <sgmltag>commandchain</sgmltag> child element it defines the command(s) 457 to run to perform the XSLT processing. The core keywords defined in 458 <xref linkend="sec-xconf-command"/> apply. The additional keywords of an XSLT 459 engine command are the following: 460 <variablelist> 461 <varlistentry> 462 <term><literal>%(xmlfile)s</literal></term> 463 <listitem><para>Replaced by the XML source file to 464 process.</para></listitem> 465 </varlistentry> 466 <varlistentry> 467 <term><literal>%(stylesheet)s</literal></term> 468 <listitem><para>Replaced by the stylesheet to use to process the 469 XML file <literal>xmlfile</literal>.</para></listitem> 470 </varlistentry> 471 <varlistentry> 472 <term><literal>%(param_list)s</literal></term> 473 <listitem><para>Replaced by the list of the XSL parameters to set. 474 The parameter pair formatting (the parameter name and its value) is 475 specified through the <sgmltag>param-format</sgmltag> attribute 476 given to the <sgmltag>engine</sgmltag> element.</para></listitem> 477 </varlistentry> 478 </variablelist> 479 </para> 480 481 <para>Attributes: 482 <variablelist> 483 <varlistentry> 484 <term>param-format</term> 485 <listitem><para>This attribute is mandatory when the engine is specified 486 through a <sgmltag>command</sgmltag>. It tells how a parameter name and 487 value pair shall be formatted when added to the XSLT engine command. 488 The formatting is given by a string containing the keywords replaced by 489 the name or value of the parameter to set: 490 491 <variablelist> 492 <varlistentry> 493 <term><literal>%(param_name)s</literal></term> 494 <listitem><para>Replaced by the name of the 495 parameter to set.</para></listitem> 496 </varlistentry> 497 <varlistentry> 498 <term><literal>%(param_value)s</literal></term> 499 <listitem><para>Replaced by the value to set to the 500 parameter.</para></listitem> 501 </varlistentry> 502 </variablelist> 503 </para></listitem> 504 </varlistentry> 505 </variablelist></para> 506 <para> 507 The following example re-writes with a user-defined command the Saxon engine 508 with an additional <option>-T</option> option: 509 <programlisting language="XML"> 510<![CDATA[<xslt> 511 <engine param-format="%(param_name)s=%(param_value)s"> 512 <command> 513 saxon-xslt -T -o %(output)s %(xmlfile)s 514 %(stylesheet)s %(param_list)s</command> 515 </engine> 516</xslt>]]></programlisting> 517 </para> 518 </section> 519 <section id="sec-xconf-imagedata" label="" xreflabel="imagedata"> 520 <title><sgmltag><imagedata></sgmltag></title> 521 <para>The imagedata element contains the rules and commands to convert 522 on the fly the images included in the docbook document.</para> 523 <para>Attributes: none</para> 524 <para> 525 The following elements occur in <sgmltag>imagedata</sgmltag>: 526 <variablelist> 527 <varlistentry> 528 <term><sgmltag>figpath</sgmltag></term> 529 <listitem><para>It defines a path where to find the images, like the 530 option <option>--fig-path</option> does.</para></listitem> 531 </varlistentry> 532 <varlistentry> 533 <term><sgmltag>figformat</sgmltag></term> 534 <listitem><para>It defines the default image format when no suffix is 535 available to deduce the actual format, like 536 <option>--fig-format</option> does.</para></listitem> 537 </varlistentry> 538 <varlistentry> 539 <term><sgmltag>formatrule</sgmltag></term> 540 <listitem><para>It specifies in which format an image must be 541 converted, depending on the context, given by some attributes: 542 <variablelist> 543 <varlistentry> 544 <term><sgmltag>docformat</sgmltag></term> 545 <listitem><para>The output document for which the rule 546 applies. When not set the rule applies for any format</para></listitem> 547 </varlistentry> 548 <varlistentry> 549 <term><sgmltag>backend</sgmltag></term> 550 <listitem><para>The rule applies only when this backend is 551 used</para></listitem> 552 </varlistentry> 553 <varlistentry> 554 <term><sgmltag>dst</sgmltag></term> 555 <listitem><para>When the conditions are met the image shall be 556 converted to this format.</para> 557 </listitem> 558 </varlistentry> 559 </variablelist> 560 </para><para>The following example: 561 <programlisting><![CDATA[<formatrule docformat="pdf" backend="xetex" dst="pdf"/>]]></programlisting> 562 tells that when a PDF document is built with the xetex backend, the 563 graphics not natively supported shall be converted to PDF. 564 </para> 565 </listitem> 566 </varlistentry> 567 <varlistentry> 568 <term><sgmltag>converter</sgmltag></term> 569 <listitem><para>It defines an image transformation rule. See 570 <xref linkend="sec-xconf-converter"/> for more 571 details.</para></listitem> 572 </varlistentry> 573 </variablelist> 574 </para> 575 </section> 576 <section id="sec-xconf-converter" label="" xreflabel="converter"> 577 <title><sgmltag><converter></sgmltag></title> 578 <para>The converter element defines a rule about how to convert on the fly 579 an image in a docbook document to the corresponding image used in the built 580 latex file. The 581 goal is to have an image format compatible with the latex engine, whatever the 582 original format is. <command>Dblatex</command> has a default set of rules, but 583 one can overwrite or add some rules.</para> 584 585 <para>Attributes: 586 <variablelist> 587 <varlistentry> 588 <term>src</term> 589 <listitem><para>Format of the original image referenced in the XML 590 document. The converter only applies to the images matching this format. 591 </para></listitem> 592 </varlistentry> 593 <varlistentry> 594 <term>dst</term> 595 <listitem><para>Target format once converted. The converter only applies 596 to the original images having the format <literal>src</literal> and that 597 need to be converted to the format <literal>dst</literal>. 598 <literal>dst</literal> can take the special value "<literal>*</literal>" 599 meaning that the rule applies for all 600 the possible target formats (e.g. eps, pdf, png).</para></listitem> 601 </varlistentry> 602 <varlistentry> 603 <term>docformat</term> 604 <listitem><para>Specify for which document output format the converter 605 applies. For example, if <literal>docformat</literal> is set to "pdf", 606 it means that 607 the converter applies only if the document output format is PDF. The 608 converter will not apply if you want to build a PostScript or DVI 609 document.</para></listitem> 610 </varlistentry> 611 <varlistentry> 612 <term>backend</term> 613 <listitem><para>The converter applies only if it is this latex engine that 614 is used. For example, it is usefull if you want to convert an image in a 615 specific way only when xetex is used.</para></listitem> 616 </varlistentry> 617 </variablelist> 618 </para> 619 620 <para>The following elements occur in <sgmltag>converter</sgmltag>: 621 <variablelist> 622 <varlistentry> 623 <term><sgmltag>commandchain</sgmltag></term> 624 <listitem><para>List of the commands to run. A 625 <sgmltag>commandchain</sgmltag> contains one or more 626 <sgmltag>command</sgmltag> elements. 627 </para></listitem> 628 </varlistentry> 629 <varlistentry> 630 <term><sgmltag>command</sgmltag></term> 631 <listitem><para>command to execute to perform the conversion, or a part of 632 the conversion if several commands are chained. See 633 <xref linkend="sec-xconf-command"/>. 634 </para></listitem> 635 </varlistentry> 636 </variablelist> 637 </para> 638 </section> 639 <section id="sec-xconf-command" label="" xreflabel="command"> 640 <title><sgmltag><command></sgmltag></title> 641 <para>The command element contains the arguments of the command to run. 642 The arguments can contain some predefined keywords that are replaced by the 643 actual values when the command is executed. The known core keywords 644 are:</para> 645 <variablelist> 646 <varlistentry> 647 <term><literal>%(src)s</literal></term> 648 <listitem><para>Replaced by the <literal>src</literal> value (original 649 image format).</para></listitem> 650 </varlistentry> 651 <varlistentry> 652 <term><literal>%(dst)s</literal></term> 653 <listitem><para>Replaced by the <literal>dst</literal> value (target 654 image format).</para></listitem> 655 </varlistentry> 656 <varlistentry> 657 <term><literal>%(input)s</literal></term> 658 <listitem><para>Replaced by the input file required by the command. In the 659 case of an image conversion, it is the filename of the original image to 660 convert.</para></listitem> 661 </varlistentry> 662 <varlistentry> 663 <term><literal>%(output)s</literal></term> 664 <listitem><para>Replaced by the name of the ouput file required by the 665 command. In the case of an image conversion, it is the filename of the 666 output image once converted.</para></listitem> 667 </varlistentry> 668 </variablelist> 669 670 <para>Attributes: 671 <variablelist> 672 <varlistentry> 673 <term>input</term> 674 <listitem><para>Standard input of the command to run. It can specify a 675 file or it can specify to use the output of the preceding command if the 676 keyword "PIPE" is used.</para></listitem> 677 </varlistentry> 678 <varlistentry> 679 <term>output</term> 680 <listitem><para>Standard output of the command to run. It can specify a 681 file or it can specify that the output shall be redirected to the next 682 command if the keyword "PIPE" is used.</para></listitem> 683 </varlistentry> 684 <varlistentry> 685 <term>shell</term> 686 <listitem><para>When set to "1" or "true", the command is run in a shell 687 environment.</para></listitem> 688 </varlistentry> 689 </variablelist> 690 </para> 691 </section> 692 <section id="sec-xconf-options" label="" xreflabel="options"> 693 <title><sgmltag><options></sgmltag></title> 694 <para>The options element lists the extra arguments to pass to 695 <command>dblatex</command>.</para> 696 </section> 697 698 </section> 699 <section><title>Deprecated Text Configuration File Format</title> 700 <para> 701 The format of the file is the following: 702 </para> 703 <itemizedlist> 704 <listitem> 705 <para> 706 Every comment starts with a “#”, and is ignored. 707 </para> 708 </listitem> 709 <listitem> 710 <para> 711 The file must contain one parameter by line. 712 </para> 713 </listitem> 714 <listitem> 715 <para> 716 The format of a parameter is the following: 717 </para> 718 <programlisting> 719<![CDATA[<keyword>: <value> 720]]> </programlisting> 721 </listitem> 722 <listitem> 723 <para> 724 Every parameter is mapped to an option that can be passed to <command>dblatex</command>. 725 </para> 726 </listitem> 727 <listitem> 728 <para> 729 An unknown parameter is silently ignored (the whole line is dropped). 730 </para> 731 </listitem> 732 <listitem> 733 <para> 734 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>. 735 </para> 736 </listitem> 737 </itemizedlist> 738 <para> 739 The following table lists the supported parameters and the corresponding command line option. 740 </para> 741<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="specparam.xml"/> 742 </section> 743 <section id="sec-conf-path"><title>Style Paths</title> 744 <para>By default <command>dblatex</command> tries to find the configuration 745 files related to a style (specified with option <option>-T</option>) in the 746 following paths, in respect of the order:</para> 747 <orderedlist> 748 <listitem><para>The current directory</para></listitem> 749 <listitem><para><filename>$HOME/.dblatex</filename></para></listitem> 750 <listitem><para><filename>/etc/dblatex</filename></para></listitem> 751 <listitem><para>The dblatex package configuration directories.</para></listitem> 752 </orderedlist> 753 <para>You can add some extra paths where to look for by setting the 754 <envar>DBLATEX_CONFIG_FILES</envar> environment variable. The paths are 755 separated by ":" in Unix like systems, and by ";" on Windows. These paths 756 are used only when nothing is found in the default paths.</para> 757 </section> 758 </section> 759 <section> 760 <title>Customization Precedence</title> 761 <para> 762 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. 763 </para> 764 <para> 765 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? 766 </para> 767 <para> 768 The options order is the following: 769 </para> 770 <itemizedlist> 771 <listitem> 772 <para> 773 If a specification file is used (<option>-S</option> option), the options are set to the specification file parameters. 774 </para> 775 </listitem> 776 <listitem> 777 <para> 778 If several specification files are used (<option>-S</option> option), the 779 precedence is given to the last specified files. 780 </para> 781 </listitem> 782 <listitem> 783 <para> 784 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). 785 </para> 786 </listitem> 787 <listitem> 788 <para> 789 If an option is passed several times, this is the last occurence that is used. 790 </para> 791 </listitem> 792 </itemizedlist> 793<example><title>Customization Precedence</title> 794 <para> 795 Let's consider the specification file containing the following parameters: 796 </para> 797 <programlisting language="XML"><![CDATA[<?xml version="1.0" ?> 798<config xmlns="http://dblatex.sourceforge.net/config"> 799 <xslt><stylesheet fileref="file3.xsl"/></xslt> 800 <options>-b pdftex</options> 801 <latex><texstyle use="mystyle1"/></latex> 802</config>]]></programlisting> 803 <para> 804 And now the command line: 805 </para> 806 <programlisting> 807<![CDATA[dblatex -b dvips -p file1.xsl -p file2.xsl -S file.specs -s mystyle2 mydoc.xml 808]]> </programlisting> 809 <para> 810 The setting used is the following: 811 </para> 812 <itemizedlist> 813 <listitem> 814 <para> 815 “-b dvips” overrides “-b pdftex” set by the spec file. 816 </para> 817 </listitem> 818 <listitem> 819 <para> 820 “-p file2.xsl” overrides “-p file1.xsl” since it is defined after, and overrides “file3.xsl” set by the spec file. 821 </para> 822 </listitem> 823 <listitem> 824 <para> 825 “-s mystyle2” override “mystyle1” set by the spec file. 826 </para> 827 </listitem> 828 </itemizedlist> 829</example> 830 </section> 831 </chapter> 832