<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"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><![CDATA[
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><![CDATA[
$ 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 <xref
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><![CDATA[
$ mkdir -p $HOME/.dblatex/mystyle/latex
$ mkdir -p $HOME/.dblatex/mystyle/xsl
]]></programlisting>
<para>Note that you could choose another configuration directory (see <xref
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><![CDATA[
$ 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><![CDATA[
$ cat $HOME/.dblatex/mystyle.conf
<?xml version="1.0" encoding="utf-8"?>
<!-- =======================================================
     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><![CDATA[
$ dblatex -T mystyle file.xml
]]></programlisting>
</step>
</procedure>

</section>
</section>