.! .! This is a RUNOFF source file that produces part of a VMS-style HELP .! library for the August DECUS TeX Collection. To build the library, .! execute MAKE_TEX_HLB.COM. .! .! Stuff I mean to fill in is marked with ??? .! Stuff that needs work in the Collection is marked with ".!" in column 1, .! except for this comment. .! .NO PAGING .NO FLAGS ALL .LEFT MARGIN 1 .RIGHT MARGIN 70 .INDENT -1 1 BIBTEX .INDENT 5 Invokes the BibTeX utility to compile a bibliography file for LaTeX. Full details can be found in "LaTeX: A Document Preparation System" by Leslie Lamport. .SKIP Format: .SKIP .INDENT +3 BIBTEX top_level_aux_file .SKIP Documentation for BibTeX can be found in TEX_ROOT:[DOC.BIBTEX]. The vast majority of this help entry was taken from the original BibTeX documentation. This documentation has since become Appendix B of "LaTeX: A Document Preparation System". .INDENT -1 2 Parameters .INDENT -1 top_level_aux_file .SKIP Specifies the name of the .AUX file to be processed by BibTeX. This file specification MUST NOT include an extension (file type). BibTeX assumes the extension .AUX as produced by the LaTeX macro package. .SKIP The file name given is used by BibTeX to construct the output file names for the log file (.BLG) and references list (.BBL). The output files are written to the location where the top level .AUX input file was found. .SKIP .INDENT -1 2 Bibliography_file .BREAK A bibliography database file may contains two types of entry - an abbreviation definition or a reference entry for citation. .INDENT -1 3 @STRING_command .INDENT 5 The @STRING command is used to define abbreviations for use by BibTeX within the bibliography database file. The command .SKIP .INDENT +3 @string{jgg1 = "Journal of Gnats and Gnus, Series~1"} .SKIP defines 'jgg1' to be the abbreviation for the string "Journal of Gnats and Gnus, Series~1". Parentheses can be used in place of the outermost braces in the @string command, and braces can be used instead of the quotation marks. The text must have matching braces. .SKIP The case of letters is ignored in an abbreviation as well as in the command name @string, so the command above could have been written: .SKIP .INDENT +3 @STRING{JgG1 = "Journal of Gnats and Gnus, Series~1"} .SKIP A @string command can appear anywhere before or between entries in a bibliography database file. However, it must come before any use of the abbreviation, so a sensible place for @string commands is at the beginning of the file. A @string command in the bibliography database file takes precedence over a definition made by the bibliography style, so it can be used to change the definition of an abbreviation such as 'Feb'. .INDENT -1 3 Entry_format .INDENT 5 A bibliography database file contains a series of reference entries like the following: .SKIP .LITERAL @BOOK{kn:gnus, AUTHOR = "Donald E. Knudson", TITLE = "1966 World Gnus Almanac", PUBLISHER = {Permafrost Press}, ADDRESS = {Novisibirsk} } .END LITERAL .SKIP The @BOOK states that this is an entry of type book. various entry types are described below. The 'kn:gnus' is the citation key, as it appears in the argument of a \cite command referring to the entry. .SKIP This entry has four fields, named AUTHOR, TITLE, PUBLISHER and ADDRESS. The meanings of these and other fields are described below. A field consists of the name, an '=' character with optional space around it, followed by its text. The text of a field is a string of characters, with no unmatched braces, surrounded by either a pair of braces or a pair of '"' characters . Entry fields are separated from one another, and from the citation key, by commas. A comma may have optional space around it. .SKIP The outermost braces that surround the entire entry may be replaced by parentheses. As in TeX input files, an end-of-line character counts as a space and one space is equivalent to many spaces. Unlike TeX, BibTeX ignores the case of letters in the entry type, citation key and field names. The above entry could have been typed as follows: .SKIP .LITERAL @BOOK(kn:gnus, author = {Donald E. Knudson}, TITLE = "1966 World Gnus Almanac", PUBLISHER = {Permafrost Press}, ADDRESS = {Novisibirsk} ) .END LITERAL .SKIP However, the case of letters does matter to LaTeX, so the citation key should appear exactly the same in all \cite commands in the LaTeX input file. .SKIP The quotes or braces can be omitted around text consisting entirely of numerals. the following two fields are equivalent: .SKIP .LITERAL Volume = "27" Volume = 27 .END LITERAL .INDENT -1 3 Entry_types .BREAK When entering a reference in the bibliography 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. .SKIP References to different types of publications contain different information; a reference to a journal 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: .SKIP .LITERAL o Required omitting the field will produce an error message and may result in a badly formatted bibliography entry. If the required information is not meaningful, you are using the wrong entry type. o Optional the field's information will be used if present, but can be omitted without causing any formatting problems. A reference should contain any available information that might help the reader, so you should include the optional field if it is applicable. o 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 bibliography entry. It's often a good idea to put all relevant information about a reference in its bibliography 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 bibliography entry. The bibliography database 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. .END LITERAL .INDENT -1 4 article_entry .INDENT 5 An article from a journal or magazine. .SKIP .LITERAL Format: @ARTICLE{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, journal, year .BREAK Optional fields: volume, number, pages, month, note, key .INDENT -1 4 book_entry .INDENT 5 A book with an explicit publisher. .SKIP .LITERAL Format: @BOOK{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author or editor, title, publisher, year .BREAK Optional fields: volume, series, address, edition, month, note, key .INDENT -1 4 booklet_entry .INDENT 5 A work that is printed and bound, but without a named publisher or sponsoring institution. .SKIP .LITERAL Format: @BOOKLET{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: title .BREAK Optional fields: author, howpublished, address, month, year, note, key .INDENT -1 4 conference_entry .INDENT 5 An article in the proceedings of a conference. This entry is identical to the 'inproceedings' entry and is included for compatibility with another text formatting system. .SKIP .LITERAL Format: @CONFERENCE{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, booktitle, year .BREAK Optional fields: editor, pages, organization, publisher, address, month, note, key .INDENT -1 4 inbook_entry .INDENT 5 A part of a book, which may be a chapter and/or a range of pages. .SKIP .LITERAL Format: @INBOOK{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author or editor, title, chapter and/or pages, publisher, year .BREAK Optional fields: volume, series, address, edition, month, note, key .INDENT -1 4 incollection_entry .INDENT 5 A part of a book with its own title. .SKIP .LITERAL Format: @INCOLLECTION{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, booktitle, year .BREAK Optional fields: editor, pages, organization, publisher, address, month, note, key .INDENT -1 4 inproceedings_entry .INDENT 5 An article in the proceedings of a conference. .SKIP .LITERAL Format: @INPROCEEDINGS{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, booktitle, year .BREAK Optional fields: editor, pages, organization, publisher, address, month, note, key .INDENT -1 4 manual_entry .INDENT 5 Technical documentation. .SKIP .LITERAL Format: @MANUAL{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: title .BREAK Optional fields: author, organization, address, edition, month, year, note, key .INDENT -1 4 mastersthesis_entry .INDENT 5 A Master's thesis. .SKIP .LITERAL Format: @MASTERSTHESIS{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, school, year .BREAK Optional fields: address, month, note, key .INDENT -1 4 misc_entry .INDENT 5 Use this type when nothing else seems appropriate. .SKIP .LITERAL Format: @MISC{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: none .BREAK Optional fields: author, title, howpublished, month, year, note, key .INDENT -1 4 phdthesis_entry .INDENT 5 A PhD thesis. .SKIP .LITERAL Format: @PHDTHESIS{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, school, year .BREAK Optional fields: address, month, note, key .INDENT -1 4 proceedings_entry .INDENT 5 The proceedings of a conference. .SKIP .LITERAL Format: @PROCEEDINGS{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: title, year .BREAK Optional fields: editor, publisher, organization, address, month, note, key .INDENT -1 4 techreport_entry .INDENT 5 A report published by a school or other institution, usually numbered within a series. .SKIP .LITERAL Format: @TECHREPORT{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, institution, year .BREAK Optional fields: type, number, address, month, note, key .INDENT -1 4 unpublished_entry .INDENT 5 A document with an author and title, but not formally published. .SKIP .LITERAL Format: @UNPUBLISHED{citation_key, required_fields [, optional_fields] } .END LITERAL .SKIP Required fields: author, title, note .BREAK Optional fields: month, year, key .INDENT -1 3 Field_text .SKIP The text of the field is enclosed in braces or double quote characters. A part of the text is said to be enclosed in braces if it lies inside a matching pair of braces other than the ones enclosing the entire entry or the entire field text. .INDENT -1 4 Names .INDENT 5 The text of an author or editor field represents a list of names. The bibliography style determines the format in which the name is printed: whether the first name or last name appears first, if the full first name or just the first initial is used, etc. The bibliography file entry simply tells BibTeX what the name is. .SKIP You should type an author's complete name and let the bibliography style decide what to abbreviate. (But an author's complete name may be "Donald~E. Knuth" or even "J.~P.~Morgan"; you should type it the way the author would like it to appear, if that's known.) .SKIP Most names can be entered in the obvious way, either with or without a comma, as in the following examples. .SKIP .LITERAL "John Paul Jones" "Jones, John Paul" "Ludwig von Beethoven" "von Beethoven, Ludwig" .END LITERAL .SKIP Some people have multiple last names - for example, Per Brinch Hansen's last name is Brinch~Hansen. His name should be typed with a comma: .SKIP .LITERAL "Brinch Hansen, Per" .END LITERAL .SKIP To understand why, you must understand how BibTeX handles names (for what follows, a "name" corresponds to a person). .SKIP Each name consists of four parts: First, von, Last, and~Jr; each part consists of a (possibly empty) list of name-tokens. For example the First part of Per Brinch~Hansen's name has the single token "Per"; the Last part has two, "Brinch" and "Hansen"; and the von and Jr parts are empty. If you had typed .SKIP .LITERAL "Per Brinch Hansen" .END LITERAL .SKIP instead, BibTeX would erroneously think "Brinch" were a First-part token, just as "Paul" is a First-part token in "John~Paul Jones". .SKIP Here's another example: .SKIP .LITERAL "Charles Louis Xavier Joseph de la Vallee Poussin" .END LITERAL .SKIP 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. .SKIP If you want BibTeX to consider something a single token, enclose it in braces. You should do this, for example, if a comma is part of a name: .SKIP .LITERAL "{Barnes and Noble, Inc.}" "{Barnes and} {Noble, Inc.}" "{Barnes} {and} {Noble,} {Inc.}" .END LITERAL .SKIP The braces surrounding the comma keep "Inc." from being interpreted as a First token; this name has only a Last part, with either one, two, or four tokens (there must be a space separating the tokens in the second and third forms). Probably the second form is slightly more meaningful, but don't lose sleep over this since only rarely will an institution be an author or editor. .SKIP So the two names .SKIP .LITERAL "von Beethoven, Ludwig" "{von Beethoven}, Ludwig" .END LITERAL .SKIP are considered by BibTeX to be different names. In the first, "Beethoven" is the Last part and "von" is the von part; in the second, which in this case happens to be incorrect, the Last part has a single token and there's no von part. The bibliography style will probably print both the same, but it may alphabetize and label them differently. .SKIP "Juniors" pose a special problem. Most people having "Jr." in their name precede it with a comma. Such a name should be entered as follows: .SKIP .LITERAL "Ford, Jr., Henry" .END LITERAL .SKIP However, a few people do not use a comma. They are handled by considering the "Jr." to be part of the last Last token: .SKIP .LITERAL "{Steele Jr.}, Guy L." "Guy L. {Steele Jr.}" .END LITERAL .SKIP This name has no Jr part. .SKIP To summarize, you may type a name in one of three forms: .SKIP .LITERAL "First von Last" "von Last, First" "von Last, Jr, First" .END LITERAL .SKIP 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. .SKIP If there are multiple authors or editors, their names must be separated by the word "and", surrounded by spaces, not enclosed in braces: .SKIP .LITERAL AUTHOR = "Ralph Alpher and Bethe, Hans and George Gamow" .END LITERAL .SKIP Since BibTeX interprets commas as separating parts of a name and "and" as separating names themselves, this example has three coauthors: Ralph Alpher, Hans Bethe, and George Gamow. If the word "and" appears as part of a name, it must be enclosed in braces, as in the example of "Barnes and Noble,~Inc." given above. If you have too many names to list in a field, you can end the list with "and others"; the standard styles appropriately append an "et al." .SKIP BibTeX's rules are actually a bit more complicated than indicated here, but this description will suffice for most names. .INDENT -1 4 Titles .INDENT 5 The bibliography style determines whether or not a title is capitalized; the titles of books usually are, the title of articles usually are not. You type a title the way it should appear if it is capitalized (you should capitalize everything but articles and unstressed conjunctions and prepositions, and even these should be capitalized as the first word or the first after a colon): .SKIP .LITERAL TITLE = "The Agony and the Ecstasy" .END LITERAL .SKIP BibTeX will change uppercase letters to lowercase if appropriate. Uppercase letters that should not be changed are enclosed in braces. The following two titles are equivalent; the "A" of "Africa" will not be made lowercase. .SKIP .LITERAL "The Gnats and Gnus of {Africa}" "The Gnats and Gnus of {A}frica" .END LITERAL .INDENT -1 4 Abbreviations .INDENT 5 Instead of an ordinary text string, the text of a field can be replaced by an abbreviation for it. An abbreviation is a string of characters that starts with a letter and does not contain a space or any of the following ten characters: .SKIP .LITERAL " # % ' ( ) , = { } .END LITERAL .SKIP The abbreviation is typed in place of the text field, with no braces or quotation marks. If 'jgg1' is an abbreviation for .SKIP .LITERAL Journal of Gnats and Gnus, Series~1 .END LITERAL .SKIP then the following are equivalent: .SKIP .LITERAL JOURNAL = jgg1 JOURNAL = "Journal of Gnats and Gnus, Series~1" .END LITERAL .SKIP Some abbreviations are predefined by the bibliography style. These always include the usual 3 letter abbreviations for the month: jan, feb, mar etc. .SKIP Bibliography styles usually contain abbreviations for the names of commonly referenced journals. Consult the Local Guide for a list of the predefined abbreviations for the bibliography styles available. .SKIP You can define your own abbreviations by using BibTeX's @STRING command. .INDENT -1 3 Field_types .INDENT 5 Below is a list of all fields recognized by the standard bibliography styles. An entry can also contain other fields, which are ignored by those styles. .INDENT -1 4 address_field .INDENT 5 Publisher's address. For major publishing houses, just the city is given. For small publishers, you can help the reader by giving the complete address. .SKIP .LITERAL Format: ADDRESS = field_text .END LITERAL .INDENT -1 4 annote_field .INDENT 5 An annotation, used only for annotated bibliography styles (which are not among the standard ones). .SKIP .LITERAL Format: ANNOTE = field_text .END LITERAL .INDENT -1 4 author_field .INDENT 5 The name(s) of the author(s). .SKIP .LITERAL Format: AUTHOR = field_text .END LITERAL .INDENT -1 4 booktitle_field .INDENT 5 Title of a book, part of which is being cited. .SKIP .LITERAL Format: BOOKTITLE = field_text .END LITERAL .INDENT -1 4 chapter_field .INDENT 5 A chapter number. .SKIP .LITERAL Format: CHAPTER = field_text .END LITERAL .INDENT -1 4 edition_field .INDENT 5 The edition of a book - for example, "second". .SKIP .LITERAL Format: EDITION = field_text .END LITERAL .INDENT -1 4 editor_field .INDENT 5 Name(s) of editor(s). If there is also an "author" field, then the "editor" field gives the editor of the book or collection in which the reference appears. .SKIP .LITERAL Format: EDITOR = field_text .END LITERAL .INDENT -1 4 howpublished_field .INDENT 5 How something strange has been published. .SKIP .LITERAL Format: HOWPUBLISHED = field_text .END LITERAL .INDENT -1 4 institution_field .INDENT 5 The institution that published the work. .SKIP .LITERAL Format: INSTITUTION = field_text .END LITERAL .INDENT -1 4 journal_field .INDENT 5 A journal name. Abbreviations are provided for many journals; see the Local Guide. .SKIP .LITERAL Format: JOURNAL = field_text .END LITERAL .INDENT -1 4 key_field .INDENT 5 Used for alphabetizing and creating a label when the "author" and "editor" fields are missing. This field should not be confused with the citation key that appears in the \cite command and at the beginning of the entry. .SKIP .LITERAL Format: KEY = field_text .END LITERAL .INDENT -1 4 month_field .INDENT 5 The month in which the work was published or, for an unpublished work, in which it was written. .SKIP .LITERAL Format: MONTH = field_text .END LITERAL .INDENT -1 4 note_field .INDENT 5 Any additional information that can help the reader. .SKIP .LITERAL Format: NOTE = field_text .END LITERAL .INDENT -1 4 number_field .INDENT 5 The number of a journal, magazine, or technical report. 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. .SKIP .LITERAL Format: NUMBER = field_text .END LITERAL .INDENT -1 4 organization_field .INDENT 5 The organization sponsoring a conference. .SKIP .LITERAL Format: ORGANIZATION = field_text .END LITERAL .INDENT -1 4 pages_field .INDENT 5 A page number or range of numbers such as "42--111"; you may also have several of these, separating them with commas: "7,41,73--97". The standard styles convert a single dash to a double. .SKIP .LITERAL Format: PAGES = field_text .END LITERAL .INDENT -1 4 publisher_field .INDENT 5 The publisher's name. .SKIP .LITERAL Format: PUBLISHER = field_text .END LITERAL .INDENT -1 4 school_field .INDENT 5 The name of the school where a thesis was written. .SKIP .LITERAL Format: SCHOOL = field_text .END LITERAL .INDENT -1 4 series_field .INDENT 5 The name of a series or set of books. When citing an entire book, the the "title" field gives its title and an optional "series" field gives the name of a series in which the book is published. .SKIP .LITERAL Format: SERIES = field_text .END LITERAL .INDENT -1 4 title_field .INDENT 5 The work's title. .SKIP .LITERAL Format: TITLE = field_text .END LITERAL .INDENT -1 4 type_field .INDENT 5 The type of a technical report - for example, "Research Note". .SKIP .LITERAL Format: TYPE = field_text .END LITERAL .INDENT -1 4 volume_field .INDENT 5 The volume of a journal or multivolume book work. .SKIP .LITERAL Format: VOLUME = field_text .END LITERAL .INDENT -1 4 year_field .INDENT 5 The year of publication or, for an unpublished work, the year it was written. This field's text should contain only numerals. .SKIP .LITERAL Format: YEAR = field_text .END LITERAL .SKIP .INDENT -1 2 Qualifiers .INDENT -1 /BIBINPUTS .SKIP /BIBINPUTS=(logical_name:) .SKIP Specifies a logical name that equates to a search list of directories containing bibliographic database files. The search procedure BibTeX uses to locate .BIB database files is to first search your default directory and then scan the directory search list specified by the /BIBINPUTS option. .SKIP Default is /BIBINPUTS=(TEX_BIB:); BibTeX looks in the directories associated with the logical name TEX_BIB. .SKIP .INDENT -1 /BSTINPUTS .SKIP /BSTINPUTS=(logical_name:) .SKIP Specifies a logical name that equates to a search list of directories containing BibTeX style (.BST) files. The search procedure BibTeX uses to locate .BST style files is to first search your default directory and then scan the directory search list specified by the /BSTINPUTS option. .SKIP Default is /BSTINPUTS=(TEX_BST:); BibTeX looks in the directories associated with the logical name TEX_BST. .SKIP .INDENT -1 /MIN_CROSSREFS .SKIP /MIN_CROSSREFS=(positive integer number) .SKIP BibTeX allows to include database entries in the reference list that have been cited `indirectly' through cross references from directly cited database entries. The /MIN_CROSSREFS qualifier allows to specify how many times this cross referencing has to occur at minimum for an entry not been explicitely cited to enable the indirect inclusion in the reference list. .SKIP The default value for /MIN_CROSSREFS is 2. .SKIP .INDENT -1 /STATS .SKIP /STATS .break /NOSTATS [D] .SKIP This qualifier is used while debugging .BST files to determine BIBTEX memory usage. .SKIP .INDENT -1 /TRACE .SKIP /TRACE .break /NOTRACE [D] .SKIP This qualifier is used while debugging .BST files to follow program flow. .SKIP