BIBTEX(1)BIBTEX(1)NAMEbibtex - make a LaTeX bibliography
SYNOPSISbibtex 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.
SEE ALSOtex(1).
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.
BIBTEX(1)