Command line interface

Making bibliographies with pybtex

The pybtex executable is used in the same way as the original bibtex command and accepts the same command line options. The only difference is that you type pybtex instead of bibtex.

For example, to compile the bibliography for a LaTeX file named book.tex, you need to type:

$ latex book
$ pybtex book
$ latex book
$ latex book  # to get cross-references right

See the BibTeX tutorial by Andrew Roberts for a basic explanation of how to use BibTeX.

Bibliography formats other then BibTeX

Pybtex is fully compatible with BibTeX’ .bib files. Besides that, Pybtex supports other bibliography formats. The list of supported formats can be seen in the output of pybtex --help.

By default, the BibTeX format is used. If a LaTeX file book.tex contains:

\bibliography{mybook}

Then this command:

$ pybtex book

will expect to find the bibliography data in a BibTeX-formatted file mybook.bib.

Pybtex can be instructed to use a different format with the --format option. For example this command:

$ pybtex --format yaml book

will tell Pybtex to look for a YAML-formatted file mybook.yaml instead of mybook.bib.

Support for additional bibliography formats can be added by plugins.

Pythonic bibliography styles

BibTeX has a built-in stack oriented programming language for defining bibliography formatting styles. This language is used in .bst style files. Pybtex is fully compatible with BibTeX’ .bst style files.

Additionally, Pybtex allows to write bibliography styles in Python. Some base BibTeX styles, including plain, alpha, unsrt, have been ported to Python already. They can be found in pybtex/style/formatting subdirectory. Additional styles can be added as plugins.

By default, Pybtex uses BibTeX’ .bst styles. You can switch the style language from BibTeX to Python with the --style-language option:

$ pybtex --style-language python book

One of the advantage of using Pythonic styles is that they can produce HTML, Markdown or plain text output besides the usual LaTeX markup. To change the output backend from LaTeX to something else, use the --output-backend option:

$ pybtex --style-language python --output-backend html book
$ pybtex --style-language python --output-backend plaintext book

(In this case Pybtex will write the bibliography to book.html or book.txt instead of book.bbl.)

Support for other markup formats can be added by plugins.

Additionally, Pythonic styles are configurable with command line options to some extent. For example, the --name-style option tells Pybtex to use a different name formatting style, --abbreviate-names forces Pybtex to use the abbreviated name format, etc. See pybtex --help for more options.

Converting bibliography databases with bibtex-convert

Pybtex comes with an additional utility called pybtex-convert. It converts bibliography databases between supported formats:

$ pybtex-convert book.bib book.yaml

Be aware that the conversion is not always lossless. For example:

• BibTeX’ string macros are substituted by their values during conversion.

• BibTeXML does not support LaTeX preambles.

• In the standard BibTeX format, names are stored as single strings. BibTexML and Pybtex’ YAML format store first name, last name, and other name parts separately.

Pretty-printing bibliography databases with bibtex-format

Sometimes you may want to convert a bibliography database to a human-readable format. Pybtex has another utility called pybtex-format for that:

$ pybtex-format book.bib book.txt
$ pybtex-format book.bib book.html

By default, the unsrt style is used for formatting. This can be changed with the --style option:

$ pybtex-format --style alpha book.bib book.txt