<?xml version='1.0'?>
<!DOCTYPE refentry
          PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
          [<!ENTITY debian "<productname>Debian</productname>">
           <!ENTITY gnu    "<acronym>GNU</acronym>">]>
<refentry id="ref-dblatex">

  <refentryinfo>
    <address>
      <email>marsgui@users.sourceforge.net</email>
    </address>
    <author>
      <firstname>Benoit</firstname>
      <surname>Guillon</surname>
      <contrib>Upstream maintainer</contrib>
    </author>
    <author>
      <firstname>Andreas</firstname>
      <surname>Hoenen</surname>
      <email>andreas.hoenen@arcor.de</email>
      <contrib>Debian maintainer</contrib>
    </author>
    <copyright>
      <year>2005</year>
      <year>2006</year>
      <year>2007</year>
      <year>2008</year>
      <year>2009</year>
      <year>2010</year>
      <year>2011</year>
      <year>2012</year>
      <year>2013</year>
      <year>2014</year>
      <year>2015</year>
      <holder>Andreas Hoenen</holder>
    </copyright>
    <legalnotice>
      <para>
        This manual page was written for the &debian; system (but it may be used
        by others).
      </para>
      <para>
        Permission is granted to copy, distribute and/or modify this document
        under the terms of the &gnu; General Public License, Version 2 or any
        later version published by the Free Software Foundation.
      </para>
      <para>
        On &debian; systems, the complete text of the &gnu; General Public
        License can be found in
        <filename>/usr/share/common-licenses/GPL</filename>.
      </para>
    </legalnotice>
    <date>March 6, 2015</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>dblatex</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">Dblatex Manual Page</refmiscinfo>
    <refmiscinfo class="source">dblatex <xi:include href="../version.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude"/></refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>dblatex</refname>
    <refpurpose>
      convert <application>DocBook</application> to
      <application>LaTeX</application>, <application>DVI</application>,
      <application>PostScript</application>, and <application>PDF</application>
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>dblatex</command>
      <arg choice="opt"><option>options</option></arg>
      <arg choice="plain">{<replaceable>file</replaceable> | -}</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para output="manpage">
      This manual page briefly documents the <command>dblatex</command>
      command. For more details read the <application>PDF</application> manual;
      see below.
    </para>

    <para>
      <command>dblatex</command> is a program that transforms your
      <application>SGML</application>/<application>XML</application>
      <application>DocBook</application> documents to
      <application>DVI</application>, <application>PostScript</application> or
      <application>PDF</application> by translating them into pure
      <application>LaTeX</application> as a first process.
      <application>MathML 2.0</application> markups are supported, too.
      <phrase output="manpage">It started as a clone of
      <application>DB2LaTeX</application>.</phrase>
    </para>
  </refsection>

  <refsection>
    <title>Options</title>

    <para>
      A summary of options is included below. <phrase output="manpage">For a
      complete description, see the <application>PDF</application>
      manual.</phrase>
    </para>

    <variablelist>
      <varlistentry>
        <term><option>-h</option></term>
        <term><option>--help</option></term>
        <listitem><simpara>Show a help message and exit.</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-b <replaceable>backend</replaceable></option></term>
        <term>
          <option>--backend=<replaceable>backend</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Backend driver to use: <parameter>pdftex</parameter> (default),
            <parameter>dvips</parameter>, or <parameter>xetex</parameter>.
            <phrase output="manual">
            See also <xref linkend="sec-process"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-B</option></term>
        <term><option>--no-batch</option></term>
        <listitem><simpara>All the tex output is printed.</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-c <replaceable>config</replaceable></option></term>
        <term><option>-S <replaceable>config</replaceable></option></term>
        <term><option>--config=<replaceable>config</replaceable></option></term>
        <listitem>
          <simpara>Configuration file. A configuration file can be used to group
          all the options and customizations to apply. <phrase output="manual">See
          <xref linkend="sec-specs"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-d</option></term>
        <term><option>--debug</option></term>
        <listitem>
          <simpara>
            Debug mode: Keep the temporary directory in which dblatex actually
            works. <phrase output="manual"><xref linkend="sec-debug"/> explains how
            you can use it.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-D</option></term>
        <term><option>--dump</option></term>
        <listitem>
          <simpara>
            Dump the error stack when an error occurs (debug purpose).
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-e <replaceable>indexstyle</replaceable></option></term>
        <term><option>--indexstyle <replaceable>indexstyle</replaceable></option></term>
        <listitem>
          <simpara>
            Index style file to pass to <command>makeindex</command> instead of
            the dblatex default index style.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-f <replaceable>figure_format</replaceable></option></term>
        <term>
          <option>--fig-format=<replaceable>figure_format</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Input figure format: <parameter>fig</parameter>,
            <parameter>eps</parameter>.  Used when not deduced from figure file
            extension. <phrase output="manual">See also
            <xref linkend="sec-figconv"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-F <replaceable>input_format</replaceable></option></term>
        <term>
          <option>--input-format=<replaceable>input_format</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Input file format: <parameter>sgml</parameter>,
            <parameter>xml</parameter> (default).
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-i <replaceable>texinputs</replaceable></option></term>
        <term>
          <option>--texinputs <replaceable>texinputs</replaceable></option>
        </term>
        <listitem>
          <simpara>Path added to <envar>TEXINPUTS</envar></simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-I <replaceable>figure_path</replaceable></option></term>
        <term>
          <option>--fig-path=<replaceable>figure_path</replaceable></option>
        </term>
        <listitem>
          <simpara>Additional lookup path of the figures. <phrase
          output="manual">See <xref linkend="sec-lookup"/>.</phrase></simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-l <replaceable>bst_path</replaceable></option></term>
        <term>
          <option>--bst-path=<replaceable>bst_path</replaceable></option>
        </term>
        <listitem>
          <simpara>Additional lookup path of the BibTeX styles. <phrase
          output="manual">See <xref linkend="sec-bibtex"/>.</phrase></simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-L <replaceable>bib_path</replaceable></option></term>
        <term>
          <option>--bib-path=<replaceable>bib_path</replaceable></option>
        </term>
        <listitem>
          <simpara>Additional lookup path of the BibTeX databases. <phrase
          output="manual">See <xref linkend="sec-bibtex"/>.</phrase></simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-m <replaceable>xslt</replaceable></option></term>
        <term>
          <option>--xslt=<replaceable>xslt</replaceable></option>
        </term>
        <listitem>
          <simpara>XSLT engine to use. The available engines are:
          xsltproc (default), 4xslt, saxon.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-o <replaceable>output</replaceable></option></term>
        <term><option>--output=<replaceable>output</replaceable></option></term>
        <listitem>
          <simpara>
            Output filename. When not specified, the input filename is used, with
            the suffix of the output format. The option is ignored if several
            books are chunked from a set. In this case the <option>-O</option>
            option is applied instead.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-O <replaceable>output_dir</replaceable></option></term>
        <term><option>--output-dir=<replaceable>output_dir</replaceable></option></term>
        <listitem>
          <simpara>
            Output directory of the books built from a set. When not specified,
            the current working directory is used instead. The option is ignored
            if a single document is outputed, and the <option>-o</option> is
            taken into account.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-p <replaceable>xsl_user</replaceable></option></term>
        <term>
          <option>--xsl-user=<replaceable>xsl_user</replaceable></option>
        </term>
        <listitem>
          <simpara>
            An <application>XSL</application> user stylesheet to use. Several
            user stylesheets can be specified, but the option order is meaningful: a user stylesheet takes precedence over previously defined user stylesheets.
            <phrase output="manual">See <xref linkend="sec-param"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-P <replaceable>param</replaceable>=<replaceable>value</replaceable></option>
        </term>
        <term>
          <option>--param=<replaceable>param</replaceable>=<replaceable>value</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Set an <application>XSL</application> parameter from command line.
            <phrase output="manual">See <xref linkend="sec-param-value"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-q</option></term>
        <term><option>--quiet</option></term>
        <listitem>
          <simpara>
            Less verbose, showing only TeX output messages and error messages.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-r <optional>plugin:</optional><replaceable>script</replaceable></option></term>
        <term>
          <option>--texpost=<optional>plugin:</optional><replaceable>script</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Script called at the very end of the tex compilation. Its role is to
            modify the tex file or one of the compilation files before the last
            round. The <replaceable>script</replaceable> can be a python plugin.
            In this case add the prefix term '<literal>plugin:</literal>'.
            <phrase output="manual">See <xref linkend="sec-texpost"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-s <replaceable>latex_style</replaceable></option></term>
        <term>
          <option>--texstyle=<replaceable>latex_style</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Latex style to apply. It can be a package name, or directly a latex
            package path. A package name must be without a directory
            path and without the '.sty' extension. On the contrary,
            a full latex package path can contain a directory path, but must ends with
            the '.sty' extension.
            <phrase output="manual">See <xref linkend="sec-custom-latex"/>.</phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-t <replaceable>format</replaceable></option></term>
        <term><option>--type=<replaceable>format</replaceable></option></term>
        <listitem>
          <simpara>
            Output format.  Available formats: <parameter>tex</parameter>,
            <parameter>dvi</parameter>, <parameter>ps</parameter>,
            <parameter>pdf</parameter> (default).
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--dvi</option></term>
        <listitem>
          <simpara>DVI output. Equivalent to <option>-tdvi</option>.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--pdf</option></term>
        <listitem>
          <simpara>PDF output. Equivalent to <option>-tpdf</option>.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--ps</option></term>
        <listitem>
          <simpara>
            PostScript output. Equivalent to <option>-tps</option>.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-T <replaceable>style</replaceable></option></term>
        <term><option>--style=<replaceable>style</replaceable></option></term>
        <listitem>
          <simpara>
            Output style, predefined are: <parameter>db2latex</parameter>,
            <parameter>simple</parameter>, <parameter>native</parameter>
            (default). <phrase output="manual">See <xref linkend="sec-style"/>.
            </phrase>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option></term>
        <term><option>--version</option></term>
        <listitem><simpara>Display the dblatex version.</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-V</option></term>
        <term><option>--verbose</option></term>
        <listitem>
          <simpara>Verbose mode, showing the running commands</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-x <replaceable>xslt_options</replaceable></option></term>
        <term>
          <option>--xslt-opts=<replaceable>xslt_options</replaceable></option>
        </term>
        <listitem>
          <simpara>
            Arguments directly passed to the <application>XSLT
            engine</application>
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-X</option></term>
        <term><option>--no-external</option></term>
        <listitem>
          <simpara>
            Disable the external text file support. This support is needed for
            callouts on external files referenced by <sgmltag>textdata</sgmltag>
            or <sgmltag>imagedata</sgmltag>, but it can be disabled if the document
            does not contain such callouts. Disabling this support can improve the
            processing performance for big documents.
          </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Files and Directories</title>
    <variablelist>
      <varlistentry>
        <term><filename>$HOME/.dblatex/</filename></term>
        <listitem>
          <simpara>
            User configuration directory.
          </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/etc/dblatex/</filename></term>
        <listitem>
          <simpara>
            System-wide configuration directory.
          </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>The predefined output styles are located in the installed package
    directory.</para>
  </refsection>

  <refsection>
    <title>Environment Variables</title>
    <variablelist>
      <varlistentry>
        <term><envar>DBLATEX_CONFIG_FILES</envar></term>
        <listitem>
          <simpara>
            Extra configuration directories that may contain some dblatex
            configuration files.
          </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Examples</title>

    <para>
      To produce <filename>myfile.pdf</filename> from
      <filename>myfile.xml</filename>:
      <screen>dblatex myfile.xml</screen>
    </para>
    <para>
      To set some XSL parameters from the command line:
      <screen>dblatex -P latex.babel.language=de myfile.xml</screen>
    </para>
    <para>
      To use your XSL stylesheet:
      <screen>dblatex -p myconfig.xsl myfile.xml</screen>
    </para>
    <para>
      To use the db2latex output style:
      <screen>dblatex -T db2latex myfile.xml</screen>
    </para>
    <para>
      To apply your own latex style:
      <screen>dblatex -s mystyle myfile.xml
dblatex -s /path/to/mystyle.sty myfile.xml</screen>
    </para>
    <para>
      To pass extra arguments to the XSLT engine:
      <screen>dblatex -x "--path /path/to/load/entity" myfile.xml</screen>
    </para>
    <para>
      To use <command>dblatex</command> and profiling:
      <screen>
xsltproc --param profile.attribute "'output'" \
         --param profile.value "'pdf'" \
         /path/to/profiling/profile.xsl \
         myfile.xml | dblatex -o myfile.pdf -
</screen>
    </para>
    <para>
      To build a set of books:
      <screen>dblatex -O /path/to/chunk/dir -Pset.book.num=all myfile.xml</screen>
    </para>
  </refsection>

  <refsection output="manpage">
    <title>See also</title>

    <para>
      The program is documented fully by <citetitle>"DocBook to LaTeX Publishing
      - User Manual"</citetitle> available in the package's documentation
      directory.
    </para>
  </refsection>

</refentry>
