The Local BibTEX Utilities

Martin Reddy

June 3, 1996

Introduction

This document lists and describes the various BibTEX utilities that are available under our local installation of L^{A}TEX 2ε. These are tools which let you maintain and manipulate your .bib bibliography databases. Currently, these include:

looktex, bibgrep . . . . . . . . . . . . search .bib files for entries containing a keyword printbib, bibprint . . . . . . . . . . produce a .dvi file listing all entries in a .bib file bibify . . . . . . . . . . . . . . . . . . . . . eliminate one pass of L^{A}TEX after running BibTEX bibclean . . . . . . . . . . . . . . . . . . . . . . . . . . . . prettyprint and syntax check BibTEX files bibcard . . . . . . . . . . . . . . . . . . . an X11 interface for maintaining BibTEX databases bibsort . . . . . . . sorts a .bib file by BibTEX tag name or by @String macro name bibtool . . . . . . . . . . maintain, sort, merge, syntax check and pretty print .bib files

1 looktex / bibgrep

These two utilities^{1} let you search through any .bib files and extract all entries containing a certain keyword. The search is case insensitive and the keyword can be any valid egrep expression (remember to quote your expression properly). The command usage is:

   bibgrep <keyword> [<file1> [<file2> ...]]

If you do not specify a list of .bib files to search, then the program will scan all of the .bib files in your $HOME/tex/bib directory.

Examples:

     bibgrep fred

Search through all of the .bib files in your $HOME/tex/bib directory, and display any entry with the name Fred in it.

1bibgrep is simply a symbolic link to looktex so the two commands are identical.

     bibgrep 'jones|smith' foo.bib

Search for any BibTEX entries in the file foo.bib that contain the name Jones or Smith.

2 printbib / bibprint

This command will take a list of .bib files and produce a .dvi file listing all of the BibTEX entries, sorted by cite key and including any ‘keyword’, ‘abstract’ and ‘comment’ fields. Command usage is as follows:

    printbib [-apalike|-acm|-alpha|-plain] <file1> [<file2> ...]

The bibliography listing is produced using the ‘plain’ style by default (i.e. [1], [2]…). However you can use the -apalike, -acm or -alpha options to specify the alternative styles of the same name. The .bib filenames can be listed on the command line with or without their .bib extensions, and the output .dvi document is written to the file bibliography.dvi.

Example:

     printbib vision vr.bib

produces a bibliography document, bibliography.dvi, containing all BibTEX entries in the files vision.bib and vr.bib

3 bibify

This utility can be used to eliminate one pass of LaTeX when compiling in conjunction with BibTEX, i.e. for a L^{A}TEX file called doc.tex, you would enter:

    latex doc; bibtex doc; bibify doc; latex doc

instead of the more normal

    latex doc; bibtex doc; latex doc; latex doc

Because bibify runs very quickly (it just updates your .aux file on the fly), this can be very handy for large documents. Note however that bibify does not work with multiple .aux files and it only operates on documents which use one of the standard bibliography styles (i.e. alpha, plain, unsrt or abbrv).

4 bibclean

The bibclean utility prettyprints input BibTEX files to stdout, and also checks the brace balance and bibliography entry syntax. It can be used to detect problems in BibTEX files that sometimes confuse even BibTEX itself, and importantly, can be used to normalise the appearance of collections of BibTEX files.

Here is a summary of the formatting actions:

• BibTEX items are formatted into a consistent structure with one key = ``value'' pair per line, and the initial @ and trailing right brace in column 1.

• Tabs are expanded into blank strings; their use is discouraged because they inhibit portability, and can suffer corruption in electronic mail.

• Long string values are split at a blank and continued onto the next line with leading indentation.

• A single blank line separates adjacent bibliography entries.

• Text outside BibTEX entries is passed through verbatim.

• Outer parentheses around entries are converted to braces.

• Personal names in author and editor field values are normalised to the form “P. D. Q. Bach”, from “P.D.Q. Bach” and “Bach, P.D.Q.”.

• Hyphen sequences in page numbers are converted to en-dashes.

• Month values are converted to standard BibTEX string abbreviations.

• In titles, sequences of upper-case characters at brace level zero are braced to protect them from being converted to lower-case letters by some bibliography styles.

• ISBN (International Standard Book Number) and ISSN (International Standard Serial Number) entry values are examined to verify the checksums of each listed number.

Refer to “bibclean -help” or “man bibclean” for further details and a list of command line options.

5 bibcard

This is an X11 based interface for BibTEX databases. The user can load in and edit existing .bib files, or create new ones. Bibliographic entries can be displayed for each type of reference defined by BibTEX. Required fields are listed first, followed by the optional fields for that type.

Files will be loaded from the current working directory unless an optional $BIBINPUTS environment variable is set. N.B. Bibcard will NOT retain the format of existing bib files when re-saved. Be sure to save a back-up of your existing bib files until you are sure bibcard’s format suits you (e.g. bibcard will throw away comments that appear between entry items).

Refer to “man bibcard” for further details.

6 bibsort

bibsort filters a BibTEX bibliography file (or fragment) on its standard input, printing a sorted bibliography to standard output. Sorting is by BibTEX tag name, or by @String macro name, and is case insensitive. The command usage is:

    bibsort [optional sort(1) switches] < infile > outfile

N.B. bibsort does not recognise bib entries with outer parentheses instead of braces^{2}. In addition to this, the user must be aware that sorting a bibliography is not without peril, for at least these reasons:

1. BibTEX has a requirement that entry tags given in crossref = tag pairs in a bibliography entry must refer to entries defined later, rather than earlier, in the bibliography file. This regrettable implementation limitation of the current (pre-1.0) BibTEX prevents arbitrary ordering of entries when crossref values are present.

2. If the BibTEX file contains interspersed commentary between “@keyword{… }” entries, this material will be considered part of the preceding entry, and will be sorted with it. Leading commentary is more common, and will be moved elsewhere in the file.

This is normally not a problem for the part 1 material before the “@Preamble”, since it is kept together at the beginning of the output stream.

3. Some kinds of bibliography files should be kept in a different order than alphabetically by tags. A good example is a bibliography file with the contents of a journal, for which publication order is likely more suitable.

Please refer to “man bibsort” for further details.

7 bibtool

Bibtool is an extremely powerful program to manipulate you BibTEX databases. It provides numerous facilities, including:

2you can use bibclean to sort this. In fact, the use of bibclean before bibsort is strongly encouraged.

Prettyprinting of bibliography files; the addition or deletion of certain fields; fields can be rewritten in a standard form or reordered. Semantic checks can be performed (e.g. finding double entries, regular expression checks etc.) Sorting can be performed on any BibTEX key, in ascending or descending ASCII order. Bibtool can also extract BibTEX entries based upon regular expressions; or extract those entries required for a document (i.e. those which appear in a document’s .aux file).

The behaviour of bibtool can be customised by creating a resource file, $HOME/.bibtoolrsc. Please refer to “bibtool -h” for a list of command line options, and “texdoc bibtool” for the program’s document file.