./_Man_NeXT_html/html1/bibtex.1.html

Manual page for BIBTEX(1)

bibtex - make a LaTeX bibliography

SYNOPSIS

bibtex auxname

DESCRIPTION

Bibtex reads the top-level auxiliary (.aux) file output during the running of latex (1) and creates a bibliography (.bbl) file that can be included in the LaTeX source file. The auxname on the command line should be given without an extension. Each \cite in the source file is looked up in bibliography files to gather together those used in the document. Then a bibliography style file is executed to write a \thebibliography environment.

The source file should have defined the bibliography (.bib) files to search with the \bibliography command, and the bibliography style (.bst) file to execute with the \bibliographystyle command. Bibtex incorporates the path searching mechanism described in the manual page for tex (1). It searches the TEXINPUTS path for .aux, .bbl, and .bst files.

Eventually there will be a section in the LaTeX manual describing the bibliography and bibliography style formats. For now, here are brief descriptions.

Bibliography File

The bibliography file (.bib) format is just about a subset of that allowed in Scribe bibliographies. Only the delimiter pairs {...} and "..." are allowed inside entries. Entries themselves can be delimited by (...) also. The = sign between field names and field values is not optional.

There are a number of conventions that should be followed when writing .bib files. These are not requirements of bibtex, but standard bibliography style files will typically expect these conventions to be followed.

References should be categorized as in Scribe into one of the categories: article, book, booklet, inbook, incollection, inproceedings, manual, mastersthesis, misc, phdthesis, proceedings, techreport, and unpublished. See the Scribe manual for the fields that must/can appear in each type of reference.

The title field should be entered in uppers-and-lowers format, where everything is capitalized except articles and unstressed conjunctions and prepositions, and even those are capitilized if they are the first word or the first word after a colon. Some style files will convert all words except the first to all lowercase. This is a mistake for things like proper nouns, so you have to tell bibtex not to touch such capital letters by enclosing them in braces, as in "Dogs of {A}merica". It is unlikely that any style file would attempt to convert book titles to lowercase, so perhaps you can omit braces in such titles.

The author and editor fields should conform to a particular format, so that the style file can parse them into parts. A name can have four parts: first, von, last, junior, each of which can consist of more than one word. For example, "John Paul von Braun, Jr." has "John Paul" as the first part, "von" as the von part, "Braun" as the last part, and "Jr." as the junior part. Use one of these formats for a name:

: First von Last
von Last, First
von Last, Junior, First

The last part is assumed to be one word, or all the words after the von part. Bibtex will treat anything in braces as one word, so use braces to surround last names that contain more than one word. The von part is recognized by looking for words that begin with lowercase letters. When possible, enter the full first name(s); style files may abbreviate by taking the first letter. Actually, the rules for isolating the name parts are a bit more complicated, so they do the right thing for names like "de la Grand Round, Chuck". There is no need for a field like Scribe's fullauthor field.

If there are multiple authors or editors, they should all be separated by the word and. Scribe's editors field should not be used, since bibtex style files can count how many names are in an editor field.

Bibliography Style File

Style (.bst) files are written in a postfix stack language. A dedicated hacker can probably figure out how to program in it by looking at an existing style file. The following descriptions of builtin functions may help. in the descriptions, "first", "second", etc., refer to the order popped.

+: Pop the top two (integer) literals and push their sum.
-: Pop the top two (integer) literals and push their difference (the first subtracted from the second).
>: Pop the top two (integer) literals, compare them, and push the integer 1 if the second is greater than the first, 0 otherwise.
<: Pop the top two (integer) literals, compare them, and push the integer 1 if the second is less than the first, 0 otherwise.
=: Pop the top two (integer or string) literals, compare them, and push the integer 1 if they're equal, 0 otherwise.
*: Pop the top two (string) literals, concatenate them (in reverse order, that is, the order in which pushed), and push the resulting string back onto the stack.
:=: Pop the top two literals and assign to the second the value of the first. Integer and string variables can be declared with "INTEGERS {i1 i2 ...}" and "STRINGS {s1 s2 ...}", respectively.
add.period$: Pop the top (string) literal, add a period to it if the last non-right-brace character isn't a period, question mark, or exclamation-mark, and push this resulting string back onto the stack.
call.type$: Execute the function corresponding to the reference classification of the current entry. For example, when processing an @INBOOK entry, call the "inbook" function if it is defined, otherwise call the "default.type" function. Functions are declared with the FUNCTION command: the first argument is the function name and the second is the body. An ENTRY command declares the variables that may be used in the style file when processing an entry. It has three brace-surrounded arguments: a list of field names that may occur in the entry (these are read-only variables returning the value assigned to the fields in the current entry), a list of local integer variables, and a list of local string variables.
change.case$: Pop the top two (string) literals; change the case of the second according to the specifications of the first, as follows. (Note: The word `letters' in the next sentence refers only to those at brace-level 0, the top-most brace level; no other characters are changed.) If the first literal is the string ul, convert all letters to lower case except the very first character in the string, which should be converted to upper case; if it's the string uu, convert all letters to upper case; if it's the string ll, convert all letters to lower case; if it's the string lu, convert all letters to upper case except the very first character in the string, which it converts to lower case. Then push this resulting string.
chr.to.int$: Pop the top (string) literal, make sure it's a single character, convert it to the corresponding ASCII-code integer, and push that integer.
cite$: Push the string used in a cite of the current entry (i.e., the codeword that appears at the beginning of the entry).
duplicate$: Push a duplicate of the stack top onto the stack.
format.name$: Pop the top three literals (they are a string, an integer, and a string literal, in that order). The last string literal represents a name list (each name corresponding to a person), the integer literal specifies which name to pick from this list, and the first string literal specifies how to format this name. Push the formatted name. The first string literal should be something like "{ff }{vv }{ll}{, jj}", or "{vv }{ll}{, jj}{, f}". In such a string, an f stands for the first name part, a v stands for the von part, etc. The doubled letters mean "put the whole part here" and the single letters mean "put an abbreviation (first letter(s)) here". These formatting letters should occur at brace level 1. If any of the corresponding parts of the name is missing, everything in the brace group corresponding to that part is omitted.
if$: Pop the top three literals (they are two function literals and an integer literal, in that order); if the integer is greater than 0, execute the second literal, else execute the first.
int.to.chr$: Pop the top (integer) literal interpreted as the ASCII code of a single character, convert it to the corresponding single-character string, and push that string.
int.to.str$: Pop the top (integer) literal, convert it to its (unique) string equivalent, and push that string.
missing$: Pop the top literal and push the integer 1 if it's a missing field (the current entry didn't have an assignment for it), 0 otherwise.
newline$: Write whatever has accumulated in the output buffer onto the .bbl file, followed by a newline character.
num.names$: Pop the top (string) literal; push the number of names the string represents: one plus the number of occurrences of the substring "and" surrounded by nonnull white-space (ignoring case differences) at the top brace level.
purify$: Pop the top (string) literal, convert upper-case letters to lower case, remove nonalphanumeric characters except for white-space characters (one or more consecutive ones get compressed to a single space), and push the resulting string.
quote$: Push the string consisting of the double-quote character.
skip$: Do nothing.
stack$: Pop and print the whole stack on the terminal and log file.
substring$: Pop the top three literals (they are the two integers literals len and start and a string literal, in that order). Push the substring of the (at most) len consecutive characters starting at the startth character (assuming 1-based indexing) if len is positive, and ending at the -startth character from the end if start is negative (where the first character from the end is the last character).
swap$: Swap the top two elements of the stack.
top$: Pop and print the top of the stack on the terminal and log file.
type$: Push the reference classification type (book, article, etc.), of the current entry onto the stack (unless either it's empty or undefined, in which case push the null string).
while$: Pop the top two (function) literals, and keep executing the second as long as the (integer) value left on the stack by executing the first is greater than 0.
width$: Pop the top (string) literal and push the integer that represents its width. The width is currently calculated in hundredths of a point, using the character widths of the amr10 font. The only white-space character with non-zero width is the space. However, the width returned should only be used in comparisons with other such widths.
write$: Pop the top (string) literal and write it on the .bbl file.

BUGS

The cacm style file is really just a skeleton so far.

HISTORY

Written by Oren Patashnik under the direction of Leslie Lamport. Ported to UNIX by Howard Trickey, June 1984.