Contents
BibTeX Reference Manager

Adapted from Oren Patashnik's sources by Eyal Doron

July, 1996

This help file describes how to create the .BIB files (reference databases) and .BST files (style files which tell BibTeX how to format the requested references). It is an adaptation of the two documentation files BTXDOC.TEX and BTXHAK.TEX distributed with BibTeX and written by its author, Oren Patashnik.

Contents

What is BibTeX

Format of .BIB Files

Entry Types

Fields

Helpful Hints

Designing BibTeX Styles

References

Glossary


What is BibTeX

This section contains a brief description of the BibTeX system. It is not comprehensive and does not cover all the commands and options. For more details see the LaTeX book [4].

BibTeX is a program written by Oren Patashnik to facilitate entering bibliographic data into LaTeX files. It was developed along with the development of LaTeX, and support for BibTeX is built into all versions of LaTeX, but BibTeX is an autonomous program that has to be invoked outside of the main LaTeX run.

BibTeX operates as follows. The bibliographic data is kept in external database files. These files contain all the relevant data, and sometimes additional information such as abstracts and keywords, but do not specify the final format in which this data will be presented. The format of these files is described later, but the important thing for now is that the data is organized into records, in which each record is identified by a unique key or label.

When an author wishes to incude a reference into his/her LaTeX document, he/she includes the LaTeX command

     \cite{first key,second key,....}

at the appropriate spot in the document. Multiple keys may be specified to refer to more than one bibliographic record. At the end of the document, the author has to specify two additional pieces of information: where is the information to be found, and how to format it. This is achieved by the commands

     \bibliography{file 1, file 2, ....}

     \bibliographystyle{style name}

The first of these commands specifies which files (and in which order) BibTeX should scan in order to find the requested keys. The second command defines a BibTeX style file which contains the formatting information. These files commonly have the extension '.bst', and control which fields are included in the output and in which order, how they are formatted, and in what order they will be sorted. The BibTeX style files are written in a somewhat arcane, postfix type language, which is described in detail here. Several styles are distributed with the BibTeX program, namely plain.bst, unsrt.bst, abbrev.bst and alpha.bst. Many publisher-specific LaTeX styles also include their own customized BibTeX styles, such as the style file "prsty.bst" distributed with the American Physical Society package RevTeX.

After the LaTeX document is prepared, the author runs the sequence LaTeX, BibTeX, LaTeX, LaTeX. The first LaTeX run writes the contents of the '\cite', '\bibliography' and '\bibliographystyle' commands to the .AUX file produced by LaTeX. The subsequent BibTeX run examines this .AUX file, reads the information, and searches the designated files for the specified records. When these records are found, BibTeX uses the style file in order to write out a file with the extension .BBL which comprises a \begin{bibliography}...\end{bibliography} LaTeX environment, with each record formatted in a separate \bibitem. The following two LaTeX runs include this file into the document and resolve all the references, replacing all the \cite commands with the appropriate reference numbers (or strings, in the case of styles such as "alpha.bst").


Format of .BIB Files

The .BIB file is the file which contains the actual bibliographic information. It consists of a series of entries, each of which represent one record. The entries have the form

@ARTICLE{My_Brilliant_Paper,

  author = {Isaac Newton and Naomi Campbell},

  title = {A Re-formulation of the Laws of Gravity with Respect to Really

           Cool Models},

  journal = {Phys. Rev. Lett.},

  volume = 152,

  pages = {1--1023}

}

Each entry consists of the following parts:

The Type of the entry (in this case @ARTICLE) is used by BibTeX to determine the formatting of the entry.

The Key or name of the entry (in this case My_Brilliant_Paper) is the string to which one refers to from within LaTeX in order to refer to the entry.

The Fields of the entry contain the actual information.

The whole entry is enclosed in a pair of braces (which can optionally be changed to parentheses), and the fields are separated from each other and from the key by commas. Whitespaces (space, tab and end-of-line) are ignored in the usual manner. BibTeX ignores the case of the entry type and field names, however case is important in the entry names.

Each entry type typically utilizes a different set of fields, some of which are required and the other optional. For a description of the standard entries and fields see the relevant section.

In addition to citation entries, BibTeX supports the following structures:

STRINGs, which contain abbreviations for use inside citation entries;

PREAMBLEs, which contain text which is included verbatim in the .BBL file produced by BibTeX.

COMMENTs, whose contents are ignored by BibTeX.

The Text of a Field

Name Fields


Entry Types

When entering a reference in the database, the first thing to decide is what type of entry it is.  No fixed classification scheme can be complete, but BibTeX provides enough entry types to handle almost any reference reasonably well.

References to different types of publications contain different information; a reference to a journal article might include the volume and number of the journal, which is usually not meaningful for a book. Therefore, database entries of different types have different fields. For each entry type, the fields are divided into three classes:

required: Omitting the field will produce a warning message and, rarely, a badly formatted bibliography entry. If the required information is not meaningful, you are using the wrong entry type. However, if the required information is meaningful but, say, already included is some other field, simply ignore the warning.

optional:The field's information will be used if present, but can be omitted without causing any formatting problems. You should include the optional field if it will help the reader.

ignored:The field is ignored. BibTeX ignores any field that is not required or optional, so you can include any fields you want in a bib file entry. It's a good idea to put all relevant information about a reference in its bib file entry - even information that may never appear in the bibliography. For example, if you want to keep an abstract of a paper in a computer file, put it in an abstract field in the paper's bib file entry. The bib file is likely to be as good a place as any for the abstract, and it is possible to design a bibliography style for printing selected abstracts. Note: Misspelling a field name will result in its being ignored, so watch out for typos (especially for optional fields, since BibTeX won't warn you when those are missing).

The following are the standard entry types, along with their required and optional fields, that are used by the standard bibliography styles. The fields within each class (required or optional) are listed in order of occurrence in the output, except that a few entry types may perturb the order slightly, depending on what fields are missing. These entry types are similar to those adapted by Brian Reid from the classification scheme of van Leunen [8] for use in the Scribe system. The meanings of the individual fields are explained in the next section. Some nonstandard bibliography styles may ignore some optional fields in creating the reference. Remember that, when used in the bib file, the entry-type name is preceded by an @ character.

ARTICLE: An article from a journal or magazine. Required fields: author, title, journal, year. Optional fields: volume, number,  pages, month, note.

BOOK: A book with an explicit publisher. Required fields: author or editor,  title, publisher, year. Optional fields: volume or number, series,  address, edition, month, note.

BOOKLET: A work that is printed and bound, but without a named publisher or sponsoring institution. Required field: title. Optional fields: author, howpublished,  address, month, year, note.

CONFERENCE: The same as INPROCEEDINGS, included for Scribe compatibility.

INBOOK: A part of a book, which may be a chapter (or section or whatever) and/or a range of pages. Required fields: author or editor, title,  chapter and/or pages, publisher, year. Optional fields: volume or number, series,  type, address, edition, month, note.

INCOLLECTION: A part of a book having its own title. Required fields: author, title, booktitle,  publisher, year. Optional fields: editor, volume or number,  series, type, chapter, pages,  address, edition, month, note.

INPROCEEDINGS: An article in a conference proceedings. Required fields: author, title, booktitle, year. Optional fields: editor, volume or number,  series, pages, address, month,  organization, publisher, note.

MANUAL: Technical documentation. Required field: title. Optional fields: author, organization,  address, edition, month, year, note.

MASTERSTHESIS: A Master's thesis. Required fields: author, title, school, year. Optional fields: type, address, month, note.

MISC: Use this type when nothing else fits. Required fields: none. Optional fields: author, title, howpublished,  month, year, note.

PHDTHESIS: A PhD thesis. Required fields: author, title, school, year. Optional fields: type, address, month, note.

PROCEEDINGS: The proceedings of a conference. Required fields: title, year. Optional fields: editor, volume or number,  series, address, month,  organization, publisher, note.

TECHREPORT: A report published by a school or other institution, usually numbered within a series. Required fields: author, title, institution, year. Optional fields: type, number, address, month, note.

UNPUBLISHED: A document having an author and title, but not formally published. Required fields: author, title, note. Optional fields: month, year.

In addition to the fields listed above, each entry type also has an optionalkey field, used in some styles for alphabetizing, for cross referencing, or for forming a \bibitem label. You should include a key field for any entry whose "author'' information is missing; the "author'' information is usually the author field, but for some entry types it can be the editor, or even the organization field (The Notes section describes this in more detail). Do not confuse the key field with the key that appears in the\cite command and at the beginning of the database entry; this field is named "key'' only for compatibility with Scribe.


Fields

Below is a description of all fields recognized by the standard bibliography styles. An entry can also contain other fields, which are ignored by those styles.

address: Usually the address of the publisher or other type of institution. For major publishing houses, van Leunen recommends omitting the information entirely. For small publishers, on the other hand, you can help the reader by giving the complete address.

annote: An annotation. It is not used by the standard bibliography styles, but may be used by others that produce an annotated bibliography.

author: The name(s) of the author(s), in the format described in the Name Fields section.

booktitle: Title of a book, part of which is being cited. See the Name Fields section for how to type titles. For book entries, use the title field instead.

chapter: A chapter (or section or whatever) number.

crossref: The database key of the entry being cross referenced.

edition: The edition of a book - for example, "Second''. This should be an ordinal, and should have the first letter capitalized, as shown here; the standard styles convert to lower case when necessary.

editor: Name(s) of editor(s), typed as indicated in the Name Fields section. If there is also an author field, then the editor field gives the editor of the book or collection in which the reference appears.

howpublished: How something strange has been published. The first word should be capitalized.

institution: The sponsoring institution of a technical report.

journal: A journal name. Abbreviations are often used here, either from the BibTeX styles or @STRING entries in the .BIB file.

key: Used for alphabetizing, cross referencing, and creating a label when the "author'' information is missing. This field should not be confused with the key that appears in the \cite command and at the beginning of the database entry.

month: The month in which the work was published or, for an unpublished work, in which it was written.

note: Any additional information that can help the reader. The first word should be capitalized.

number: The number of a journal, magazine, technical report, or of a work in a series. An issue of a journal or magazine is usually identified by its volume and number; the organization that issues a technical report usually gives it a number; and sometimes books are given numbers in a named series.

organization: The organization that sponsors a conference or that publishes a manual.

pages: One or more page numbers or range of numbers, such as 42--111 or 7,41,73--97 or 43+   (the '+' in this last example indicates pages following that don't form a simple range). To make it easier to maintain Scribe-compatible databases, the standard styles convert a single dash (as in 7-33) to the double dash used in TeX to denote number ranges (as in 7--33).

publisher: The publisher's name.

school: The name of the school where a thesis was written.

series: The name of a series or set of books. When citing an entire book, the title field gives its title and an optional series field gives the name of a series or multi-volume set in which the book is published.

title: The work's title.

type: The type of a technical report - for example, "Research Note''.

volume: The volume of a journal or multivolume book.

year: The year of publication or, for an unpublished work, the year it was written. Generally it should consist of four numerals, such as 1984, although the standard styles can handle any year whose last four nonpunctuation characters are numerals, such as '(about 1984)'.


Helpful Hints

This section gives some random tips that aren't documented elsewhere, at least not in this detail. They are, roughly, in order of least esoteric to most. First, however, a brief spiel.

I understand that there's often little choice in choosing a bibliography style - journal X says you must use style Y and that's that. If you have a choice, however, I strongly recommend that you choose something like the plain standard style. Such a style, van Leunen [8] argues convincingly, encourages better writing than the alternatives - more concrete, more vivid.

The Chicago Manual of Style [1], on the other hand, espouse the author-date system, in which the citation might appear in the text as '(Jones, 1986)'. I argue that this system, besides cluttering up the text with information that may or may not be relevant, encourages the passive voice and vague writing. Furthermore the strongest arguments for using the author-date system - like "it's the most practical'' - fall flat on their face with the advent of computer-typesetting technology. For instance the Chicago Manual contains, right in the middle of page 401, this anachronism: "The chief disadvantage of [a style like plain] is that additions or deletions cannot be made after the manuscript is typed without changing numbers in both text references and list.'' LaTeX, obviously, sidesteps the disadvantage.

Finally, the logical deficiencies of the author-date style are quite evident once you've written a program to implement it. For example, in a large bibliography, using the standard alphabetizing scheme, the entry for '(Aho et al., 1983b)' might be half a page later than the one for '(Aho et al., 1983a)'. Fixing this problem results in even worse ones. What a mess. (I have, unfortunately, programmed such a style, and if you're saddled with an unenlightened publisher or if you don't buy my propaganda, it's available from the Rochester style collection.)

Ok, so the spiel wasn't very brief; but it made me feel better, and now my blood pressure is back to normal. Here are the tips for using BibTeX with the standard styles (although many of them hold for nonstandard styles, too).

1.	With BibTeX's style-designing language you can program general database manipulations, in addition to bibliography styles. For example it's a fairly easy task for someone familiar with the language to produce a database-key/author index of all the entries in a database. Consult the Local Guide to see what tools are available on your system.

2.	The standard style's thirteen entry types do reasonably well at formatting most entries, but no scheme with just thirteen formats can do everything perfectly. Thus, you should feel free to be creative in how you use these entry types (but if you have to be too creative, there's a good chance you're using the wrong entry type).

3.	Don't take the field names too seriously. Sometimes, for instance, you might have to include the publisher's address along with the publisher's name in the publisher field, rather than putting it in the address field. Or sometimes, difficult entries work best when you make judicious use of the note field.

4.	Don't take the warning messages too seriously. Sometimes, for instance, the year appears in the title, as in The 1966 World Gnus Almanac. In this case it's best to omit the year field and to ignore BibTeX's warning message.

5.	If you have too many names to list in an author or editor field, you can end the list with "and others''; the standard styles appropriately append an "et al.''

6.	In general, if you want to keep BibTeX from changing something to lower case, you enclose it in braces. You might not get the effect you want, however, if the very first character after the left brace is a backslash. The "special characters'' item later in this section explains.

7.	For Scribe compatibility, the database files allow an @COMMENT command; it's not really needed because BibTeX allows in the database files any comment that's not within an entry. If you want to comment out an entry, simply remove the '@' character preceding the entry type.

8.	The standard styles have journal abbreviations that are computer-science oriented; these are in the style files primarily for the example. If you have a different set of journal abbreviations, it's sensible to put them in @STRING commands in their own database file and to list this database file as an argument to LaTeX's \bibliography command (but you should list this argument before the ones that specify real database entries).

9.	It's best to use the three-letter abbreviations for the month, rather than spelling out the month yourself. This lets the bibliography style be consistent. And if you want to include information for the day of the month, the month field is usually the best place. For example

    month = jul # "~4,"

will probably produce just what you want.

10.	If you're using the unsrt style (references are listed in order of citation) along with the \nocite{*} feature (all entries in the database are included), the placement of the \nocite{*} command within your document file will determine the reference order. If the command is placed at the beginning of the document, the entries will be listed in exactly the order they occur in the database; if it's placed at the end, the entries that you explicitly \cite or \nocite will occur in citation order, and the remaining database entries will be in database order.

11.	For theses, van Leunen recommends not giving the school's department after the name of the degree, since schools, not departments, issue degrees. If you really think that giving the department information will help the reader find the thesis, put that information in the address field.

12.	The MASTERSTHESIS and PHDTHESIS entry types are so named for Scribe compatibility;  MINORTHESIS and MAJORTHESIS probably would have been better names. Keep this in mind when trying to classify a non-U.S. thesis.

13.	Here's yet another suggestion for what to do when an author's name appears slightly differently in two publications. Suppose, for example, two journals articles use these fields.

    author = "Donald E. Knuth"

    .  .  .

    author = "D. E. Knuth"

There are two possibilities. You could (1) simply leave them as is, or (2) assuming you know for sure that these authors are one and the same person, you could list both in the form that the author prefers (say, 'Donald E. Knuth'). In the first case, the entries might be alphabetized incorrectly, and in the second, the slightly altered name might foul up somebody's electronic library search. But there's a third possibility, which is the one I prefer. You could convert the second journal's field to

    author = "D[onald] E. Knuth"

This avoids the pitfalls of the previous two solutions, since BibTeX alphabetizes this as if the brackets weren't there, and since the brackets clue the reader in that a full first name was missing from the original. Of course it introduces another pitfall - 'D[onald] E. Knuth' looks ugly - but in this case I think the increase in accuracy outweighs the loss in aesthetics.

14.	LaTeX's comment character '%' is not a comment character in the database files.

15.	Unlike TeX and LaTeX, braces can't be escaped in BibTeX entries, i.e. \{ and \} have to match just as the unescaped brace pairs have to match.

16.	Here's a more complete description of the "author'' information referred to in previous sections. For most entry types the "author'' information is simply the author field. However: For the BOOK and INBOOK entry types it's the author field, but if there's no author then it's the editor field; for the MANUAL entry type it's the author field, but if there's no author then it's the organization field; and for the PROCEEDINGS entry type it's the editor field, but if there's no editor then it's the organization field.

17.	When creating a label, the alpha style uses the "author'' information described above, but with a slight change -  for the MANUAL and PROCEEDINGS entry types, the key field takes precedence over the organization field. Here's a situation where this is useful.

   organization = "The Association for Computing Machinery",

   key = "ACM"

Without the key field, the alpha style would make a label from the first three letters of information in the organization field; alpha knows to strip off the 'The ', but it would still form a label like '[Ass86]', which, however intriguing, is uninformative. Including the key field, as above, would yield the better label '[ACM86]'.

You won't always need the key field to override the organization, though: With

    organization = "Unilogic, Ltd.",

for instance, the alpha style would form the perfectly reasonable label '[Uni86]'.

18.	To BibTeX, an accented character is really a special case of a "special character'', which consists of everything from a left brace at the top-most level, immediately followed by a backslash, up through the matching right brace. For example in the field

    author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} G{\"o}del"

there are just two special characters, '{\'{E}douard}' and '{\"o}' (the same would be true if the pair of double quotes delimiting the field were braces instead). In general, BibTeX will not do any processing of a TeX or LaTeX control sequence inside a special character, but it will process other characters. Thus a style that converts all titles to lower case would convert

    The {\TeX BOOK\NOOP} Experience

to

    The {\TeX book\NOOP} experience

(the 'The' is still capitalized because it's the first word of the title).

This special-character scheme is useful for handling accented characters, for getting BibTeX's alphabetizing to do what you want, and, since BibTeX counts an entire special character as just one letter, for stuffing extra characters inside labels. The file XAMPL.BIB distributed with BibTeX gives examples of all three uses.


Designing BibTeX Styles

This section, along with the standard-style documentation file btxbst.doc, should explain how to modify existing style files and to produce new ones. If you're a serious style hacker you should be familiar with van Leunen [8] for points of style,with Lamport [4] and Knuth [3] for formatting matters, and perhaps with Scribe [7] for compatibility details. And while you're at it, if you don't read the great little book by Strunk and White [6], you should at least look at its entries in the database and the reference list to see how BibTeX handles multiple names.

To create a new style, it's best to start with an existing style that's close to yours, and then modify that. This is true even if you're simply updating an old style for BibTeX version 0.99 (I've updated four nonstandard styles, so I say this with some experience). If you want to insert into a new style some function you'd written for an old (version 0.98i) style, keep in mind that the order of the arguments to the assignment (:=) function has been reversed. When you're finished with your style, you may want to try running it on the entire XAMPL.BIB database to make sure it handles all the standard entry types.

If you find any bugs in the standard styles, or if there are things you'd like to do with bibliography-style files but can't, please complain to Oren Patashnik.

Style file description

Commands

The built-in functions

Name formatting


References

[1] The Chicago Manual of Style, pages 400--401. University of Chicago Press, thirteenth edition, 1982.

[2] Charles Louis Xavier Joseph de la Vallée Poussin. A strong form of the prime number theorem, 19th century.

[3] Donald E. Knuth. The TeXbook. Addison-Wesley, 1984.

[4] Leslie Lamport. LaTeX: A Document Preparation System. Addison-Wesley, 1986.

[5] Oren Patashnik. BibTeXing. Documentation for general BibTeX users, January 1988.

[6] William Strunk, Jr. and E. B. White. The Elements of Style. Macmillan, third edition, 1979.

[7] Unilogic, Ltd., Pittsburgh. Scribe Document Production System User Manual, April 1984. Chapter twelve and appendices E8 through E10 deal with  bibliographies.

[8] Mary-Claire van Leunen. A Handbook for Scholars. Knopf, 1979.


Glossary

@ARTICLE

@BOOK

@BOOKLET

@CONFERENCE

@INBOOK

@INCOLLECTION

@INPROCEEDINGS

@MANUAL

@MASTERSTHESIS

@MISC

@PHDTHESIS

@PROCEEDINGS

@TECHREPORT

@UNPUBLISHED

@STRING

@PREAMBLE

@COMMENT


The Text of a Field

The BibTeX fields are the objects which contain the actual information of the entry. The simplest type of fields consist of a string, enclosed in a pair of double quotes, or equivalently a pair of curly braces (note that \{ and \} are considered as braces in BibTeX, and have to match). Strings which are purely numeric may be inputted with or without the enclosing quotes or braces.

BibTeX frequently formats the entry fields, in accordance with the .BST file used at the time. For example, it could capitalize certain strings such as titles. If you wish to protect part of a string from such manipulations, you can enclose it in an additional pair of braces. BibTeX will then leave it alone. Another example of the use of grouping is in name fields, i.e. fields which refer to people's names (typically authors or editors).

BibTeX also supports the use of abbreviations in place of explicit strings. Abbreviations are strings which do not include spaces or any of the following characters:

   "  #  %  '  (  )  ,  =  {  }

Abbreviations can be defined in the following places:

1.	In the style (.BST) files, using the MACRO command.

2.	In the .BIB file, using the @STRING construct.

In order to use an abbreviation, include it in the field definition without enclosing it in double quotes or braces, e.g.

  journal = prl,

It is also possible to concatenate a mixture of strings and abbreviations in a field definition, using the concatenation character '#'. For example, the following line

  journal = prl # ", the green plague"

will expand to

  journal = "Phys. Rev. Lett., the green plague"

Abbreviations which are defined in @STRINGs in a .BIB file take precedence over those defined in .BST styles. @STRINGs may appear anywhere in a .BIB file, however they must appear before the first time they are used. Consequently, a good place for @STRINGs is either at the beginning of a file, or in a separate file which preceeds all others in a '\bibliography' LaTeX command.


Name Fields

This section describes BibTeX's names (which appear in the author or editor field) in slightly more detail than what appears in Appendix B of the LaTeX book. In what follows, a "name'' corresponds to a person. (Recall that you separate multiple names in a single field with the word "and'', surrounded by spaces, and not enclosed in braces. This item concerns itself with the structure of a single name.)

Each name consists of four parts: First, von, Last, and Jr; each part consists of a (possibly empty) list of name-tokens. The Last part will be nonempty if any part is, so if there's just one token, it's always a Last token.

Recall that Per Brinch Hansen's name should be typed

    "Brinch Hansen, Per"

The First part of his name has the single token "Per''; the Last part has two tokens, "Brinch'' and "Hansen''; and the von and Jr parts are empty. If you had typed

    "Per Brinch Hansen"

instead, BibTeX would (erroneously) think "Brinch'' were a First-part token, just as "Paul'' is a First-part token in "John Paul Jones'', so this erroneous form would have two First tokens and one Last token.

Here's another example:

    "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"

This name has four tokens in the First part, two in the von, and two in the Last. Here BibTeX knows where one part ends and the other begins because the tokens in the von part begin with lower-case letters.

In general, it's a von token if the first letter at brace-level 0 is in lower case. Since technically everything in a "special character'' is at brace-level 0, you can trick BibTeX into thinking that a token is or is not a von token by prepending a dummy special character whose first letter past the TeX control sequence is in the desired case, upper or lower.

To summarize, BibTeX allows three possible forms for the name:

    "First von Last"

    "von Last, First"

    "von Last, Jr, First"

You may almost always use the first form; you shouldn't if either there's a Jr part, or the Last part has multiple tokens but there's no von part.


Style file description

You write bibliography styles in a postfix stack language. It's not too hard to figure out how by looking at the standard-style documentation, but this description fills in a few details (it will fill in more details if there's a demand for it).

Basically the style file is a program, written in an unnamed language, that tells BibTeX how to format the entries that will go in the reference list (henceforth "the entries'' will be "the entry list'' or simply "the list'', context permitting). This programming language has ten commands, described in the next subsection. These commands manipulate the language's objects: constants, variables, functions, the stack, and the entry list. (Warning: The terminology in this documentation, chosen for ease of explanation, is slightly different from BibTeX's. For example, this documentation's "variables'' and "functions'' are both "functions'' to BibTeX. Keep this in mind when interpreting BibTeX's error messages.)

There are two types of functions: built-in ones that BibTeX provides, and ones you define using either the MACRO or FUNCTION command.

Your most time-consuming task, as a style designer, will be creating or modifying functions using the FUNCTION command (actually, becoming familiar with the references listed above will be more time consuming, but assume for the moment that that's done).

Let's look at a sample function fragment. Suppose you have a string variable named label and an integer variable named lab.width, and suppose you want to append the character 'a' to label and to increment lab.width:

    .  .  .

    label "a" * 'label :=          % label := label * "a"

    lab.width #1 + 'lab.width :=   % lab.width := lab.width + 1

    .  .  .

In the first line, label pushes that variable's value onto the stack. Next, the "a" pushes the string constant 'a' onto the stack. Then the built-in function * pops the top two strings and pushes their concatenation. The 'label pushes that variable's name onto the stack. And finally, the built-in function := pops the variable name and the concatenation and performs the assignment. BibTeX treats the stuff following the % as a comment in the style file. The second line is similar except that it uses #1, with no spaces intervening between the '#' and the '1', to push this integer constant.

The nonnull spacing here is arbitrary: multiple spaces, tabs, or newlines are equivalent to a single one (except that you're probably better off not having blank lines within commands, as explained shortly).

For string constants, absolutely any printing character is legal between two consecutive double quotes, but BibTeX here (and only here) treats upper- and lower-case equivalents as different. Furthermore, spacing is relevant within a string constant, and you mustn't split a string constant across lines (that is, the beginning and ending double quotes must be on the same line).

Variable and function names may not begin with a numeral and may not contain any of the ten restricted characters on page 143 of the LaTeX book, but may otherwise contain any printing characters. Also, BibTeX considers upper- and lower-case equivalents to be the same.

Integers and strings are the only value types for constants and variables (booleans are implemented simply as 0-or-1 integers). There are three kinds of variables:

global variables: These are either integer- or string-valued, declared using an INTEGERS or STRINGS command.

entry variables: These are either integer- or string-valued, declared using the ENTRY command. Each has a value for each entry on the list (example: a variable label might store the label string you'll use for the entry).

fields: These are string-valued, read-only variables that store the information from the database file; their values are set by the READ command. As with entry variables, each has a value for each entry.


Commands

There are ten style-file commands: Five (ENTRY, FUNCTION, INTEGERS,  MACRO, and STRINGS) declare and define variables and functions; one (READ) reads in the database information; and four (EXECUTE, ITERATE, REVERSE, and SORT) manipulate the entries and produce output. Although the command names appear here in upper case, BibTeX ignores case differences.

Some restrictions: There must be exactly one ENTRY and one READ command; the ENTRY command, all MACRO commands, and certain FUNCTION commands (see next subsection's description of call.type$) must precede the READ command; and the READ command must precede the four that manipulate the entries and produce output.

Also it's best (but not essential) to leave at least one blank line between commands and to leave no blank lines within a command; this helps BibTeX recover from any syntax errors you make.

You must enclose each argument of every command in braces. Look at the standard-style documentation for syntactic issues not described in this section. Here are the ten commands:

ENTRY: Declares the fields and entry variables. It has three arguments, each a (possibly empty) list of variable names. The three lists are of: fields, integer entry variables, and string entry variables. There is an additional field that BibTeX automatically declares, crossref, used for cross referencing. And there is an additional string entry variable automatically declared, sort.key$, used by the SORT command. Each of these variables has a value for each entry on the list.

EXECUTE:   Executes a single function. It has one argument, the function name.

FUNCTION:   Defines a new function. It has two arguments; the first is the function's name and the second is its definition. You must define a function before using it; recursive functions are thus illegal.

INTEGERS:   Declares global integer variables. It has one argument, a list of variable names. There are two such automatically-declared variables,  entry.max$ and global.max$, used for limiting the lengths of string variables. You may have any number of these commands, but a variable's declaration must precede its use.

ITERATE:   Executes a single function, once for each entry in the list, in the list's current order (initially the list is in citation order, but t he SORT command may change this). It has one argument, the function name.

MACRO:   Defines a string macro. It has two arguments; the first is the macro's name, which is treated like any other variable or function name, and the second is its definition, which must be double-quote-delimited. You must have one for each three-letter month abbreviation; in addition, you should have one for common journal names. The user's database may override any definition you define using this command. If you want to define a string the user can't touch, use the FUNCTION command, which has a compatible syntax.

READ:   Dredges up from the database file the field values for each entry in the list. It has no arguments. If a database entry doesn't have a value for a field (and probably no database entry will have a value for every field), that field variable is marked as missing for the entry.

REVERSE:   Exactly the same as the ITERATE command except that it executes the function on the entry list in reverse order.

SORT:   Sorts the entry list using the values of the string entry variable sort.key$. It has no arguments.

STRINGS:   Declares global string variables. It has one argument, a list of variable names. You may have any number of these commands, but a variable's declaration must precede its use.


The built-in functions

Before we get to the built-in functions, a few words about some other built-in objects. There is one built-in string entry variable, sort.key$, which the style program must set if the style is to do sorting. There is one built-in field, crossref, used for the cross referencing feature. And there are two built-in integer global variables, entry.max$ and global.max$, which are set by default to some internal BibTeX constants; you should truncate strings to these lengths before you assign to string variables, so as to not generate any BibTeX warning messages.

There are currently 37 built-in functions. Every built-in function with a letter in its name ends with a '$'. In what follows, "first'', "second'', and so on refer to the order popped. A "literal'' is an element on the stack, and it will be either an integer value, a string value, a variable or function name, or a special value denoting a missing field. If any popped literal has an incorrect type, BibTeX complains and pushes the integer 0 or the null string, depending on whether the function was supposed to push an integer or string.

>:   Pops the top two (integer) literals, compares them, and pushes the integer 1 if the second is greater than the first, 0 otherwise.

<:   Analogous.

=:   Pops the top two (both integer or both string) literals, compares them, and pushes the integer 1 if they're equal, 0 otherwise.

+:   Pops the top two (integer) literals and pushes their sum.

-:   Pops the top two (integer) literals and pushes their difference (the first subtracted from the second).

*:   Pops the top two (string) literals, concatenates them (in reverse order, that is, the order in which pushed), and pushes the resulting string.

:=:   Pops the top two literals and assigns to the first (which must be a global or entry variable) the value of the second.

add.period$:   Pops the top (string) literal, adds a '.' to it if the last non'}' character isn't a '.', '?', or '!', and pushes this resulting string.

call.type$:   Executes the function whose name is the entry type of an entry. For example if an entry is of type book, this function executes the book function. When given as an argument to the ITERATE command, call.type$ actually produces the output for the entries. For an entry with an unknown type, it executes the function default.type. Thus you should define (before the READ command) one function for each standard entry type as well as a default.type function.

change.case$:   Pops the top two (string) literals; it changes 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, except perhaps for "special characters'', described in Section 4.) If the first literal is the string 't', it converts to lower case all letters except the very first character in the string, which it leaves alone, and except the first character following any colon and then nonnull white space, which it also leaves alone; if it's the string 'l', it converts all letters to lower case; and if it's the string 'u', it converts all letters to upper case. It then pushes this resulting string.  If either type is incorrect, it complains and pushes the null string; however, if both types are correct but the specification string (i.e., the first string) isn't one of the legal ones, it merely pushes the second back onto the stack, after complaining.  (Another note: It ignores case differences in the specification string; for example, the strings t and T are equivalent for the purposes of this built-in function.)

chr.to.int$:   Pops the top (string) literal, makes sure it's a single character, converts it to the corresponding ASCII integer, and pushes this integer.

cite$:   Pushes the string that was the \cite-command argument for this entry.

duplicate$:   Pops the top literal from the stack and pushes two copies of it.

empty$:   Pops the top literal and pushes the integer 1 if it's a missing field or a string having no non-white-space characters, 0 otherwise.

format.name$:   Pops the top three literals (they are a string, an integer, and a string literal). 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, as explained in the next subsection. Finally, this function pushes the formatted name.

if$:   Pops the top three literals (they are two function literals and an integer literal, in that order); if the integer is greater than 0, it executes the second literal, else it executes the first.

int.to.chr$:   Pops the top (integer) literal, interpreted as the ASCII integer value of a single character, converts it to the corresponding single-character string, and pushes this string.

int.to.str$:   Pops the top (integer) literal, converts it to its (unique) string equivalent, and pushes this string.

missing$:   Pops the top literal and pushes the integer 1 if it's a missing field, 0 otherwise.

newline$:   Writes onto the bbl file what's accumulated in the output buffer. It writes a blank line if and only if the output buffer is empty. Since write$ does reasonable line breaking, you should use this function only when you want a blank line or an explicit line break.

num.names$:   Pops the top (string) literal and pushes the number of names the string represents - one plus the number of occurrences of the substring "and'' (ignoring case differences) surrounded by nonnull white-space at the top brace level.

pop$:   Pops the top of the stack but doesn't print it; this gets rid of an unwanted stack literal.

preamble$:   Pushes onto the stack the concatenation of all the @PREAMBLE strings read from the database files.

purify$:   Pops the top (string) literal, removes nonalphanumeric characters except for white-space characters and hyphens and ties (these all get converted to a space), removes certain alphabetic characters contained in the control sequences associated with a "special character'', and pushes the resulting string.

quote$:   Pushes the string consisting of the double-quote character.

skip$:   Is a no-op.

stack$:   Pops and prints the whole stack; it's meant to be used for style designers while debugging.

substring$:   Pops the top three literals (they are the two integers literals len and start, and a string literal, in that order). It pushes the substring of the (at most) len consecutive characters starting at the startth character (assuming 1-based indexing) if start 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$:   Swaps the top two literals on the stack.

text.length$:   Pops the top (string) literal, and pushes the number of text characters it contains, where an accented character (more precisely, a "special character'') counts as a single text character, even if it's missing its matching right brace, and where braces don't count as text characters.

text.prefix$:   Pops the top two literals (the integer literal len and a string literal, in that order). It pushes the substring of the (at most) len consecutive text characters starting from the beginning of the string.  This function is similar to substring$, but this one considers a "special character'', even if it's missing its matching right brace, to be a single text character (rather than however many ASCII characters it actually comprises), and this function doesn't consider braces to be text characters; furthermore, this function appends any needed matching right braces.

top$:   Pops and prints the top of the stack on the terminal and log file. It's useful for debugging.

type$:   Pushes the current entry's type (book, article, etc.), but pushes the null string if the type is either unknown or undefined.

warning$:   Pops the top (string) literal and prints it following a warning message. This also increments a count of the number of warning messages issued.

while$:   Pops the top two (function) literals, and keeps executing the second as long as the (integer) literal left on the stack by executing the first is greater than 0.

width$:   Pops the top (string) literal and pushes the integer that represents its width in some relative units (currently, hundredths of a point, as specified by the June 1987 version of the cmr10 font; the only white-space character with nonzero width is the space). This function takes the literal literally; that is, it assumes each character in the string is to be printed as is, regardless of whether the character has a special meaning to TeX, except that "special characters'' (even without their right braces) are handled specially. This is meant to be used for comparing widths of label strings.

write$:   Pops the top (string) literal and writes it on the output buffer (which will result in stuff being written onto the bbl file when the buffer fills up).

Note that the built-in functions while$ and if$ require two function literals on the stack. You get them there either by immediately preceding the name of a function by a single quote, or, if you don't feel like defining a new function with the FUNCTION command, by simply giving its definition (that is, giving what would be the second argument to the FUNCTION command, including the surrounding braces). For example the following function fragment appends the character 'a' if the string variable named label is nonnull:

    .  .  .

    label "" =

      'skip$

      { label "a" * 'label := }

    if$

    .  .  .

A function whose name you quote needn't be built in like skip$ above - it may, for example, be a field name or a function you've defined earlier.


Name formatting

What's in a name? The Name Fields section pretty much describes this. Each name consists of four parts: First, von, Last, and Jr; each consists of a list of name-tokens, and any list but Last's may be empty for a nonnull name. This subsection describes the format string you must supply to the built-in function format.name$.

Let's look at an example of a very long name. Suppose a database entry [2] has the field

  author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"

and suppose you want this formatted "last name comma initials''. If you use the format string

    "{vv~}{ll}{, jj}{, f}?"

BibTeX will produce

    de~la Vall{\'e}e~Poussin, C.~L. X.~J?

as the formatted string.

Let's look at this example in detail. There are four brace-level 1 pieces to this format string, one for each part of a name. If the corresponding part of a name isn't present (the Jr part for this name), everything in that piece is ignored. Anything at brace-level 0 is output verbatim (the presumed typo '?' for this name is at brace-level 0), but you probably won't use this feature much.

Within each piece a double letter tells BibTeX to use whole tokens, and a single letter, to abbreviate them (these letters must be at brace-level 1); everything else within the piece is used verbatim (well, almost everything - read on). The tie at the end of the von part (in {vv~}) is a discretionary tie - BibTeX will output a tie at that point if it thinks there's a need for one; otherwise it will output a space. If you really, really, want a tie there, regardless of what BibTeX thinks, use two of them (only one will be output); that is, use {vv~~}. A tie is discretionary only if it's the last character of the piece; anywhere else it's treated as an ordinary character.

BibTeX puts default strings between tokens of a name part: For whole tokens it uses either a space or a tie, depending on which one it thinks is best, and for abbreviated tokens it uses a period followed by either a space or a tie. However it doesn't use this default string after the last token in a list; hence there's no period following the 'J' for our example. You should have used

    "{vv~}{ll}{, jj}{, f.}"

to get BibTeX to produce the same formatted string but with the question mark replaced by a period. Note that the period should go inside the First-name piece, rather than where the question mark was, in case a name has no First part.

If you want to override BibTeX's default between-token strings, you must explicitly specify a string. For example suppose you want a label to contain the first letter from each token in the von and Last parts, with no spaces; you should use the format string

    "{v{}}{l{}}"

so that BibTeX will produce 'dlVP' as the formatted string. You must give a string for each piece whose default you want overridden (the example here uses the null string for both pieces), and this string must immediately follow either the single or double letter for the piece. You may not have any other letters at brace-level 1 in the format string.


@ARTICLE

An article from a journal or magazine. Required fields: author, title, journal, year. Optional fields: volume, number,  pages, month, note.


@BOOK

A book with an explicit publisher. Required fields: author or editor,  title, publisher, year. Optional fields: volume or number, series,  address, edition, month, note.


@BOOKLET

A work that is printed and bound, but without a named publisher or sponsoring institution. Required field: title. Optional fields: author, howpublished,  address, month, year, note.


@CONFERENCE

The same as INPROCEEDINGS, included for Scribe compatibility.


@INBOOK

A part of a book, which may be a chapter (or section or whatever) and/or a range of pages. Required fields: author or editor, title,  chapter and/or pages, publisher, year. Optional fields: volume or number, series,  type, address, edition, month, note.


@INCOLLECTION

A part of a book having its own title. Required fields: author, title, booktitle,  publisher, year. Optional fields: editor, volume or number,  series, type, chapter, pages,  address, edition, month, note.


@INPROCEEDINGS

An article in a conference proceedings. Required fields: author, title, booktitle, year. Optional fields: editor, volume or number,  series, pages, address, month,  organization, publisher, note.


@MANUAL

Technical documentation. Required field: title. Optional fields: author, organization,  address, edition, month, year, note.


@MASTERSTHESIS

A Master's thesis. Required fields: author, title, school, year. Optional fields: type, address, month, note.


@MISC

Use this type when nothing else fits. Required fields: none. Optional fields: author, title, howpublished,  month, year, note.


@PHDTHESIS

A PhD thesis. Required fields: author, title, school, year. Optional fields: type, address, month, note.


@PROCEEDINGS

The proceedings of a conference. Required fields: title, year. Optional fields: editor, volume or number,  series, address, month,  organization, publisher, note.


@TECHREPORT

A report published by a school or other institution, usually numbered within a series. Required fields: author, title, institution, year. Optional fields: type, number, address, month, note.


@UNPUBLISHED

A document having an author and title, but not formally published. Required fields: author, title, note. Optional fields: month, year.


@STRING

An abbreviation which can be used inside fields of other entry types. The syntax of @STRINGs is e.g.

@STRING{ prl = "Phys. Rev. Lett." }

The abbreviation "prl" may now be used in place of the full string, as detailed above.


@PREAMBLE

BibTeX supports a @PREAMBLE command for the database files. This command's syntax is just like @STRING's, except that there is no name or equals-sign, just the string. Here's an example:

    @PREAMBLE{ "\newcommand{\noopsort}[1]{} "

             # "\newcommand{\singleletter}[1]{#1} " }

(note the use of concatenation here, too). The standard styles output whatever information you give this command (LaTeX macros most likely) directly to the bbl file. We'll look at one possible use of this command, based on the \noopsort command just defined.

The issue here is sorting (alphabetizing). BibTeX does a pretty good job, but occasionally weird circumstances conspire to confuse BibTeX: Suppose that you have entries in your database for the two books in a two-volume set by the same author, and that you'd like volume 1 to appear just before volume 2 in your reference list. Further suppose that there's now a second edition of volume 1, which came out in 1973, say, but that there's still just one edition of volume 2, which came out in 1971. Since the plain standard style sorts by author and then year, it will place volume 2 first (because its edition came out two years earlier) unless you help BibTeX. You can do this by using the year fields below for the two volumes:

    year = "{\noopsort{a}}1973"

    .  .  .

    year = "{\noopsort{b}}1971"

According to the definition of \noopsort, LaTeX will print nothing but the true year for these fields. But BibTeX will be perfectly happy pretending that \noopsort specifies some fancy accent that's supposed to adorn the 'a' and the 'b'; thus when BibTeX sorts it will pretend that 'a1973' and 'b1971' are the real years, and since 'a' comes before 'b', it will place volume 1 before volume 2, just what you wanted. By the way, if this author has any other works included in your database, you'd probably want to use instead something like {\noopsort{1968a}}1973 and {\noopsort{1968b}}1971, so that these two books would come out in a reasonable spot relative to the author's other works (this assumes that 1968 results in a reasonable spot, say because that's when the first edition of volume 1 appeared).

There is a limit to the number of @PREAMBLE commands you may use, but you'll never exceed this limit if you restrict yourself to one per database file; this is not a serious restriction, given the concatenation feature.


@COMMENT

The entire contents of the @COMMENT construct are simply ignored by BibTeX. This is supported for scribe compatibility only: BibTeX in any case ignores any text found between entries. The simplest method to comment out an entry in the .BIB file is to remove the '@' character from its type declaration.