BibTeX database files are in a text format with a few conventions you will want to know. See Formatting Names and Publication Types) for answers to common questions.
It helps to know what the parts of a BibTeX file are. Here's a trivial example to help illustrate. First we have a macro definition:
@string{PACT = "International Conference on Processors, Architectures and Compilation Techniques"}
|
Next a single entry:
@proceedings{pact02,
booktitle = PACT,
Year = 2002,
Month = sep,
Address = "Harvard Square"}
|
The terminology we'll use to describe the entry is as follows:
@publication-type{citation-key, field-name = value}
|
Any value can be either a quoted string (using either `""' or `{}') or a number, or a macro (like `PACT' in the above example).
Each publication is assigned a type, which along with carrying some information about the publication, determines how it will be formatted later in conjunction with BibTeX styles.
A cite key is a unique identifier for a given reference. BibTeX scans your document for
occurrences of a cite command with a cite key embedded in it, and translates it into a
properly formatted reference. Several patterns are common
in choosing cite keys, from simple ones such as "lastnameYEAR" to more complicated
abbreviations of journal names and author names. BibDesk will automatically
generate cite keys for you (See section Citation Keys), or you can enter your own in the editor.
BibDesk takes a fairly strict interpretation of the valid characters for cite keys,
and the characters " "@',\#}{~%" (including the space character) are never allowed,
while you will be warned if you use one of "&$^" in a cite key. Cite keys are
essentially TeX commands, so you should avoid using underscores, for instance, if you
ever need to print the actual cite key itself.
BibTeX defines numerous required and optional fields for each type, such as "Title" or "Author". BibDesk's editor will highlight the required fields in red, and optional fields are black. Any field may be used with any type, however, and you can add your own fields to entries and use them with custom bibliography styles. For instance, you can add a "Keywords" field to all of your entries, then modify a bibliography style to print out the list of keywords in your bibliography.
Field entries are subject to limitations of TeX itself, and if you copy-and-paste a title with characters that are special to TeX, such as `$', errors will occur when processing your file with BibTeX and TeX. Other than that, any text is valid for a BibTeX field, and is not limited to bibliographic information (some people store addresses in a BibTeX database).
Author and editor lists in BibTeX files are written as a single string using the word "and" as a separator between names, like this example:
"Adam Maxwell and Michael O. McCracken" |
If a name has two parts, commas are used to determine which parts are the first, middle and last names. For example, the following two names are the same:
"Adam Maxwell" "Maxwell, Adam" |
BibTeX also handles more complicated names. Prefixes to given names such as `van' or `van den' and suffixes such as `Jr.' or `III' are OK:
"van den Huevel, Jr., Johan A" |
Macros are a time saving feature that save typing when you have to repeat the same long journal name over and over. If you define a macro, you can just type the short version and BibTeX will substitute the full version in processing.
Macro definitions look like this:
@string{PACT = "International Conference on Processors, Architectures and Compilation Techniques"}
|
To use the macro, just use the first part of the definition without quotes (here PACT)
as the value for a field in the BibTeX file, as in the example above.
Note that in our example, we also used a macro `sep', which was not defined in the example. Common three-letter month names are usually defined appropriately in your Style Files for the document's language, and may also be abbreviated depending on the citation style.
BibDesk supports reading, editing and saving BibTeX macros. See Editing Fields with Macros for further information.
Crossrefs are another time saving feature, and allow changes in a single entry (here termed the "parent") to propagate to the entries which link to it (here termed the "children").
For example, this entry defines a single volume in a series of books, but is missing some key information, such as Title and Author! This is supplied by the item whose cite key matches the `Crossref' field's value.
@book{book-crossref,
Crossref = {whole-set},
Edition = {Second},
Note = {This is a cross-referencing BOOK entry},
Series = {The Art of Computer Programming},
Title = {Seminumerical Algorithms},
Volume = 2,
Year = {{\noopsort{1973c}}1981}}
|
Continuing our example, this parent entry contains the information common to all of the books in the series:
@book{whole-set,
Author = {Knuth, Donald E.},
Note = {Seven volumes planned (this is a cross-referenced set of BOOKs)},
Publisher = {Addison-Wesley},
Series = {Four volumes},
Title = {The Art of Computer Programming},
Year = {{\noopsort{1973a}}{\switchargs{--90}{1968}}}}
|
One important caveat when working with crossreferences in BibTeX is that all parent items must follow their children in the file. BibDesk can sort the items for you with "Sort Publications for Crossrefs" in the Publication menu, or you can allow BibDesk to automatically sort the items when saving (See section Crossref).
BibTeX uses style files (extension .bst) to produce formatted bibliographies
for various publishers. You probably have numerous BibTeX styles installed on your
computer, and many more can be found on CTAN, the
Comprehensive TeX Archive Network.
Writing your own BibTeX style files is possible, but not recommended for the faint of heart (or even the not-so-faint of heart). Patrick W. Daly's custom-bib package is a valuable asset when you need a customized bibliography style, as it walks you through a semi-automatic creation process.
The canonical reference for BibTeX itself is Oren Patashnik's BibTeXing, which you may have already as btxdoc.pdf in your TeX tree. Standard references such as `The LaTeX Companion' are very helpful in understanding and debugging BibTeX, and searching the TeX FAQ is usually a good idea as well.