# Writing a Bibliography

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

## Using Bibliography Entries

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

### A Bibliography

    <bibliography><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>

## Using BibTeX Databases

Instead of writing the bibliographic materials in DocBook you can reuse some already available BibTeX databases. Of course, this feature is specific to `dblatex`, that will automatically call `bibtex` if some bibtex databases are used.

To do so, write a `bibliodiv` containing an empty `bibliomixed` element having a `bibtex` processing instruction specifying the databases to use and the style to apply.

More precisely here are the attributes supported by the `bibtex` PI:

bibfiles

- This attribute is mandatory and specifies the databases to use. The databases are separated by commas, and must not contain the file suffix (`.bib`). 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 `-L` option.

bibstyle

- Optional attribute specifying the bibliographic style to apply for rendering the databases. You can also change globally the style to apply with the `latex.biblio.style`.

  The actual style file used by `bibtex` is searched in the default paths, but some extra paths can be added by using the `-l` option.

mode

- Optional print mode. The available values are:

  all

- Print all the entries contained in the databases.

cited

- Print only the entries cited in the document.

notcited

- Print only the entries not cited in the document.

When the attribute is not used, the `latex.biblio.output` parameter is used as print mode. By default the print mode is set to 'all'.

Some `bibliodiv`s embedding bibliographic entries can be mixed with some `bibliodiv`s using BibTeX databases, as shown by eg-bibmixed.

### Bibliography using BibTeX databases

    <bibliography><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><?bibtex bibfiles="bib/latex-bib" bibstyle="alpha"?></bibliomixed>
      </bibliodiv>
      <bibliodiv><title>Cited Bibtex References</title>
        <bibliomixed><?bibtex bibfiles="bib/database1,bib/database2"
                              bibstyle="plain"
                              mode="cited"?></bibliomixed>
      </bibliodiv>
    </bibliography>

## Natbib Citations

You can apply natbib citation styles by playing with the citation role attribute, or with a `dblatex` processing instruction. The natbib use is enabled only when the `citation.natbib.use` 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 `citation.natbib.options` parameter.

When using the role attribute, simply type the natbib citation command to apply. When using the `dblatex` PI, put the natbib command in the `citestyle` attribute.

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).

Here are some examples:

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

You can use a global natib citation style with the `citation.default.style` parameter. By default the parameter is empty, and therefor is not used.