path: root/biblio/bibtex/vms/bibtex.rnh

.!
.! 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