Writing a Bibliography
Prev | Chapter 3. Using dblatex | Next

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

Example 3.15. 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 Example 3.16, “Bibliography using BibTeX databases”.

Example 3.16. 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.

Prev | Up | Next
Creating an Index | Home | Document Revisions