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

<section xmlns:xi="http://www.w3.org/2001/XInclude">

  <title>Writing a Bibliography</title>

  <para>

   A bibliography (<sgmltag>bibliography</sgmltag>) can be written and put anywhere in the document. It appears as a chapter or a section and is composed by several divisions (<sgmltag>bibliodiv</sgmltag>) displayed as sections or subsections.

  </para>

  <section><title>Using Bibliography Entries</title>

  <para>

   The writer selects information that describes each bibliography entry (<sgmltag>biblioentry</sgmltag>), and chooses the presentation order. The titles and authors are displayed first.

  </para>

<example><title>A Bibliography</title>

  <programlisting>

<title>Bibliography Example</title> 

  <bibliodiv><title>References</title>

    <biblioentry>

      <title>Document title</title>

      <author><firstname>J.</firstname><surname>Doe</surname></author>

      <pubsnumber>DEX000567325</pubsnumber>

    </biblioentry>

  </bibliodiv>

  <bibliodiv><title>White papers</title>

    <biblioentry>

      <title>Technical notes</title>

      <authorgroup>

        <author><firstname>J.</firstname><surname>Doe</surname></author>

        <author><firstname>R.</firstname><surname>Marion</surname></author>

      </authorgroup>

      <pubsnumber>DEX000704520</pubsnumber>

    </biblioentry>

  </bibliodiv>

</bibliography>

]]>  </programlisting>

</example>

</section>

<section id="sec-bibtex"><title>Using BibTeX Databases</title>

<para>Instead of writing the bibliographic materials in DocBook you can reuse

some already available BibTeX databases. Of course, this feature is specific to

<command>dblatex</command>, that will automatically call <command>bibtex</command>

if some bibtex databases are used.</para>

<para>To do so, write a <sgmltag>bibliodiv</sgmltag> containing an empty

<sgmltag>bibliomixed</sgmltag> element having a

<literal>bibtex</literal> processing instruction specifying the databases to use

and the style to apply.</para>

<para>More precisely here are the attributes supported by the

<literal>bibtex</literal> PI:

<variablelist id="bibtex-attributes">

<varlistentry><term>bibfiles</term>

<listitem><para>This attribute is mandatory and specifies the databases to use.

The databases are separated by

commas, and must not contain the file suffix (<literal>.bib</literal>). The bibfiles

paths must be absolute or relative to the base directory of the document. You

can also add some bibfile paths by using the <option>-L</option> option.</para>

</listitem>

</varlistentry>

<varlistentry><term>bibstyle</term>

<listitem>

<para>Optional attribute specifying the bibliographic style to apply for rendering

the databases. You can also change globally the style to apply with the

<parameter>latex.biblio.style</parameter>.</para>

<para>The actual style file used by

<command>bibtex</command> is searched in the default paths, but some extra paths

can be added by using the <option>-l</option> option.</para>

</listitem>

</varlistentry>

<varlistentry><term>mode</term>

<listitem>

<para>Optional print mode. The available values are:

  <variablelist id="biblio-output-modes">

  <varlistentry><term>all</term>

  <listitem><para>Print all the entries contained in the databases.</para></listitem>

  </varlistentry>

  <varlistentry><term>cited</term>

  <listitem><para>Print only the entries cited in the document.</para></listitem>

  </varlistentry>

  <varlistentry><term>notcited</term>

  <listitem><para>Print only the entries <emphasis>not</emphasis> cited in the

  document.</para></listitem>

  </varlistentry>

  </variablelist>

</para>

<para>When the attribute is not used, the

  <parameter>latex.biblio.output</parameter> parameter is used as print mode. By

  default the print mode is set to 'all'.</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>Some <sgmltag>bibliodiv</sgmltag>s embedding bibliographic entries can be mixed with some <sgmltag>bibliodiv</sgmltag>s using BibTeX databases, as shown by 

linkend="eg-bibmixed"/>.</para>

<example id="eg-bibmixed"><title>Bibliography using BibTeX databases</title>

  <programlisting>

<title>Bibliography Example</title> 

  <bibliodiv><title>References</title>

    <biblioentry>

      <title>Document Title</title>

      <author><firstname>J.</firstname><surname>Doe</surname></author>

      <pubsnumber>DEX000567325</pubsnumber>

    </biblioentry>

  </bibliodiv>

  <bibliodiv><title>Bibtex References</title>

    <bibliomixed></bibliomixed>

  </bibliodiv>

  <bibliodiv><title>Cited Bibtex References</title>

    <bibliomixed>

                          bibstyle="plain"

                          mode="cited"?></bibliomixed>

  </bibliodiv>

</bibliography>

]]>  </programlisting>

</example>

</section>

<section id="sec-natbib"><title>Natbib Citations</title>

<para>You can apply natbib citation styles by playing with the citation role

attribute, or with a <literal>dblatex</literal> processing instruction. The

natbib use is enabled only when the <parameter>citation.natbib.use</parameter>

paramater is set to 1; if not (default) the role attribute or PI are not taken

into account even if present. The natbib package can be loaded with user specific

options by setting the <parameter>citation.natbib.options</parameter>

parameter.</para>

<para>When using the role attribute, simply type the natbib citation command to

apply. When using the <literal>dblatex</literal> PI, put the natbib command in

the <sgmltag>citestyle</sgmltag> attribute.</para>

<para>If you need to put some square brackets "[ ]" in the citation texts, enclose

the whole text with "{ }" to protect them (as you would do in latex).</para>

<para>Here are some examples:</para>

<programlisting>

<citation role="\citep[see][chap. #2]">texbook</citation>

<citation role="\citep[see][{[chap. #2]}]">texbook</citation>

<citation>texbook</citation>

<citation>texbook</citation>

</para>]]></programlisting>

<para>You can use a global natib citation style with the

<parameter>citation.default.style</parameter> parameter. By default the

parameter is empty, and therefor is not used.</para>

</section>

</section>