"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<section id="sec-style"><title>Output Formatting Style</title>

<para>The output rendering done by <command>dblatex</command> can be widely

customized like explained in <xref linkend="sec-custom"/>. By default several

rendering styles are provided, that one can choose by using the option

<option>-T</option> (see <xref linkend="eg-style"/>). The available styles are:</para>

<variablelist>

<varlistentry><term>native</term>

<listitem>

<para>The rendering uses the default LaTeX stylesheets. It is the style used by

default if dblatex has been configured without using the option

<option>--style</option>.</para>

</listitem>

</varlistentry>

<varlistentry><term>simple</term>

<listitem>

<para>The rendering is very close to original latex rendering. The wrapper

around the default latex packages is very thin.</para>

</listitem>

</varlistentry>

<varlistentry><term>db2latex</term>

<listitem>

<para>The rendering tries to be as close as possible to the

<ulink url="http://db2latex.sourceforge.net">DB2LaTeX</ulink> formatting.</para>

</listitem>

</varlistentry>

</variablelist>

<example id="eg-style"><title>Choosing the DB2LaTeX style</title>

<programlisting>

dblatex -T db2latex file.xml

]]></programlisting>

</example>

<section><title>How it works</title>

<para>The rendering style stuff is under the <filename>latex/</filename>

directory. You can see the XSL stylesheets under <filename>xsl/</filename>

as the way to produce latex with as little as possible docbook specific things

(even if a large amount of latex packages are used to do the work). Then, it's

up to LaTeX stylesheets to format the document as you wish.</para>

<para>The organization under <filename>latex/</filename> is as follow:</para>

<variablelist>

<varlistentry><term><filename>contrib</filename></term>

<listitem>

<para>Contains the non-default available LaTeX stylesheets (simple and db2latex).

</para>

</listitem>

</varlistentry>

<varlistentry><term><filename>graphics</filename></term>

<listitem>

<para>Default graphics used in the admonitions (e.g. <sgmltag>warning</sgmltag>).

These graphics are used by the default output formatting.

</para>

</listitem>

</varlistentry>

<varlistentry><term><filename>scripts</filename></term>

<listitem>

<para>Scripts used to compile with <command>latex</command> or

<command>pdflatex</command>.

</para>

</listitem>

</varlistentry>

<varlistentry><term><filename>specs</filename></term>

<listitem>

<para>Contains all the configuration files describing the available styles.

A specification file must have the extension .specs, .conf, or .xml to be

detected as a style description, and its basename is the name of the style.

For example the style db2latex is described by the configuration file

<filename>db2latex.xml</filename>.

</para>

<para>When <command>dblatex</command> is executed with no parameter, the usage

is displayed. In particular, the list of the available styles is given, like

this:

<programlisting>

$ dblatex

dblatex [options] file.{sgml|xml}

Options:

-t {pdf|ps|dvi|tex|xml}: output format

...

-T style               : available latex styles (db2latex, native, simple)

]]></programlisting>

The list is built by scanning the specs files found under

<filename>specs/</filename>. The spec file syntax is described in 

linkend="sec-specs"/>.

</para>

</listitem>

</varlistentry>

<varlistentry><term><filename>style</filename></term>

<listitem>

<para>Default LaTeX stylesheets.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section><title>Adding a New Formatting Style</title>

<para>To add a new formatting style, do the following steps:</para>

<procedure>

<step><para>Let's create the style directories that will contain all the

specific data. We choose to put them under the default

<command>dblatex</command> user configuration directory.</para>

<programlisting>

$ mkdir -p $HOME/.dblatex/mystyle/latex

$ mkdir -p $HOME/.dblatex/mystyle/xsl

]]></programlisting>

<para>Note that you could choose another configuration directory (see 

linkend="sec-conf-path"/> for more details).</para>

</step>

<step><para>Create the latex stylesheets you need. It must define the expected

DocBook interface and include some core definitions from the default latex

stylesheets (cf. <xref linkend="sec-custom-latex"/>). Create also your XSL

stylesheet if necessary.</para></step>

<step><para>Put these files under the appropriate directories:</para>

<programlisting>

$ mv mytexstyle.sty $HOME/.dblatex/mystyle/latex/.

$ mv param.xsl $HOME/.dblatex/mystyle/xsl/.

]]></programlisting>

</step>

<step><para>Create a configuration file under the directory

<filename>$HOME/.dblatex</filename>. The configuration file must point to the

new latex stylesheet, and give the specific parameters. Example:</para>

<programlisting>

$ cat $HOME/.dblatex/mystyle.conf

     Dblatex config file for my new style.

     Note that the directories are relative to mystyle.conf

     ======================================================= -->

<config xmlns="http://dblatex.sourceforge.net/config">

  <latex>

    <texinputs>mystyle/latex//</texinputs>

    <texstyle use="mytexstyle"/>

  </latex>

  <xslt>

    <stylesheet fileref="mystyle/xsl/param.xsl"/>

  </xslt>

  <options>-f fig</options>

</config>

]]></programlisting>

</step>

<step><para>That's it. Try to compile your document with your style, and check

the output. The configuration file basename is the name of the style to

call.</para>

<programlisting>

$ dblatex -T mystyle file.xml

]]></programlisting>

</step>

</procedure>

</section>

</section>