(Last modified Tue Nov 28 15:21 2006)

bibfile — A tool for manipulating $BibTeX$ files

bibfile is a tool for performing a variety of manipulations on $BibTeX$ files. It is particularly useful for collections of files, each containing a single entry, but is also useful for the more usual bib files containing many entries. It is a command-line program controlled by command-line options.

bibfile reads one or more bib files named on the command line, examines or manipulates the bib entries it found as controlled by command-line options, and then either writes all the entries the standard output or a named file, writes the entries individually to files whose name is based on the entry key, shows statistics or information, or (if no relevant options are given) does nothing.

Among the possible manipulations are:

discarding fields from entries
discarding entire entries
sorting fields within entries
rebracing or requoting field values
unjustifying fields so each occupies a single line
standardizing author and editor names
calculating a key for each entry
adding a key field or date fields
expanding crossrefs

In this description, each LIST is a comma-separated list of field names or entry types.

Output

bibfile produces no output unless specifically asked. The possibilities are:

Entire entries: The entries are written to the output if -showEntry is given.
Entire entries, with each field on a single line: Ordinarily, field values are divided across one or more lines as necessary to keep each line within a certain length (bibfile uses 72). The -single option causes each field to occupy a single line.
Entry types: The type of each entry is written to the output if -showType is given.
File names for each entry: The name of the file containing each entry is written if -showFname is present. If a single file contains several entries, the file name appears once for each entry.
Keys for each entry: The key for each entry is written if -showKey is present.
Field values only: The values of specific fields are written to the output if -showFields=LIST is given. Only the values are written, not the field names or anything identifying the entries they appear in (unless -showFname or -showKey are given).
Statistics: Various statistics are produced by -stats: the number of entries (-stats or -stats=1), possibly augmented by the number of fields and counts of each field type (-stats=2).

By default, output is sent to the standard output. Other possibilities are:

Output to a file: Output is sent to a file by -out=FNAME.
Each entry to its own file: Each entry is written to its own file by -toKeyFile, in the current directory or a named directory (-toKeyFile=DIR).
Message output: Messages are written to the error output by default, but can be redirected to a file (-msg=FNAME) or to the standard output (-msg).

Calculating some field values

bibfile calculates keys based on the authors' last names, the year, and the title. Up to three authors' names are used, and the first letters of up to four title words. Example: Smith2003-a for "The Artichoke", Jones+Smith2004-ac for "The Artichoke: A comparison", Baker+Jones+Smith2005-acfs for "The Artichoke: A comparison and field study of common varieties", and Baker+Jones+2006-a for "On Artichokes" with four or more authors. -keyHelp describes the process and lists title words whose first letters aren't used.

Add a field whose value is the calculated key: The field name will be key. -keyHelp gives help on how keys are calculated and what the key will be for a particular entry.
Get the entry key from the key field value: This requires that each entry have a key field, of course.
Check keys and key field values: -checkKey checks that each entry's key and (if present) key field value are the same as the calculated key.

bibfile also calculates a few other fields.

Add a field whose value is today's date: -addToday=FIELD adds a field named FIELD whose value is today's date (in "yyyy-MM-dd DD" form).
Present author names in standard form: -standardizeAuthors puts "first middle last" author names in the standard "last, first middle" form where possible. Names that appear special in some way are left unchanged and a message is shown (for example, "Frederick P. Brooks, Jr."). Any "van", "von", "de la", etc. is treated as a middle name. Names that are already in standard form are left alone.
Expand crossrefs: -expandCrossrefs causes bibfile to expand crossref fields as BibTeX does. The crossreferenced entries are sought in the current directory by default, or (with -expandCrossrefs=DIR) in the named directory.

Sorting fields within entries

By default, fields are written in the order they were read, but -sortFields causes them to be sorted. bibfile has a default field sort order (shown by -sortOrder), or you can specify your own sort order with -sortOrder=LIST.

Filtering out fields within entries, or entire entries

Discarding fields within entries: This can be done either by listing fields to be discarded (-discardFields=LIST) or by listing fields to be kept (-keepFields=LIST) or by asking for standard fields only (-keepStandardFields).
Discarding entries by the fields they contain: The entries to discard may be specified by either listing fields whose presence causes the entry to be discarded (-discardByFields=LIST) or by listing fields whose presence causes the entry to be kept (-keepByFields=LIST).
Discarding entries by type: This can be done either by listing entry types to be discarded (-discardTypes=LIST) or by listing types to be kept (-keepTypes=LIST).

Bracing and quoting

$BibTeX$ allows each field value to be either quoted in double quotes or braced in curly braces. It is common to see quoted fields, even though quotes in the field values must be escaped. It's probably better to use braced fields, which avoid this problem.

Bracing all fields: The -braceAll option causes all fields to be braces, regardless of whether they were braced or quoted before.
Quoting all fields: The -quoteAll option causes all fields to be quoted.

Information and help

In case you need to check a field name or entry type and don't want to pull out the Lamport book or other reference, -entryTypes lists the standard entry types, -fieldNames the standard field names, and -fieldName=ETYPE the required and optional fields for the given entry type.

bibfile displays help if -help is given or if no options or arguments are given.

Implementation

bibfile is implemented in java, and embodied as a jarfile (with manifest so it can be executed directly) and a script for running it.

Thomas A. Alspaugh
Assistant Professor, Informatics Dept.
School of Information and Computer Sciences