path: root/info/bibtex/bibtex.hlp

!!! ======================================================================
!!!  @Digital-HELP-Text-file{
!!!     filename        = "bibtex.hlp",
!!!     version         = "1.0",
!!!     date            = "2 January 1993",
!!!     ISO-date        = "1993.01.02",
!!!     time            = "21:51:14.28 CST",
!!!     author          = "George D. Greenwade",
!!!     address         = "Department of Economics and Business Analysis
!!!                        College of Business Administration
!!!                        P. O. Box 2118
!!!                        Sam Houston State University
!!!                        Huntsville, Texas, USA 77341-2118",
!!!     email           = "bed_gdg@SHSU.edu (Internet)
!!!                        BED_GDG@SHSU     (BITNET)
!!!                        SHSU::BED_GDG    (THENET)",
!!!     telephone       = "(409) 294-1266",
!!!     FAX             = "(409) 294-3712",
!!!     supported       = "yes",
!!!     archived        = "*Niord.SHSU,edu:[FILESERV.VMS-LATEX-HELP]",
!!!     keywords        = "VMS, help, librarian, LaTeX, BibTeX",
!!!     codetable       = "ISO/ASCII",
!!!     checksum        = "45243 659 3657 26287",
!!!     docstring       = "This is a replacement for BIBTEX.HLP in the VMS
!!!                        Help Library.  It is a modification of the DECUS
!!!                        BIBTEX.HLP file with the LaTeX command strings
!!!                        copied into a higher level so that the command
!!!                          HELP BIBTEX COMMAND topic
!!!                        is immediately accessible.
!!!                        
!!!                        The checksum field above contains a CRC-16
!!!                        checksum as the first value, followed by the
!!!                        equivalent of the standard UNIX wc (word 
!!!                        count) utility output of lines, words, and
!!!                        characters.  This is produced by Robert 
!!!                        Solovay's checksum utility."
!!! }
!!! ======================================================================
1 BibTeX
      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.

 Format:

    BIBTEX bibliography-file-spec
2 Parameters
 bibliography-file-spec

 Specifies the name of the bibliography database file to  be  compiled
 by  BibTeX.   If the file specification does not include a file type,
 BibTeX assumes a default type of BIB.
2 Command_Qualifiers
/BIBINPUTS
 /BIBINPUTS=(name,...)

 Specify directories containing input files, and the  order  in  which
 they will be searched to locate each input file.  A null value in the
 list indicates the current directory.  The search procedure TeX  uses
 to  locate  input files is to first search your default directory and
 then search each of  the  directories  specified  by  the  /BIBINPUTS
 option.

 Default  is  /BIBINPUTS=(TEX_BIB:);  TeX  looks  in   the   directory
 associated with the logical name TEX_BIB.
/STATS
 /STATS
 /NOSTATS [D]

 This qualifier is used while debugging .BST files to determine BIBTEX
 memory usage.
/TEXINPUTS
 /TEXINPUTS=(name,...)

 Specify directories containing input files, and the  order  in  which
 they will be searched to locate each input file.  A null value in the
 list indicates the current directory.  The search procedure TeX  uses
 to  locate  input files is to first search your default directory and
 then search each of  the  directories  specified  by  the  /TEXINPUTS
 option.

 Default  is  /TEXINPUTS=(TEX_INPUTS);  TeX  looks  in  the  directory
 associated with the logical name TEX_INPUTS.
/TRACE
 /TRACE
 /NOTRACE [D]

 This qualifier is used while debugging .BST files to  follow  program
 flow.
2 bib_files
 This help entry contains the same information as Appendix  B  of  the
 LaTeX  manual.   It  describes  the format of a bibliography database
 (.BIB) file.

 A bibliography database file may contains two types  of  entry  -  an
 abbreviation definition or a reference entry for citation.
3 @STRING_command
      The @STRING command is used to define abbreviations for  use  by
 BibTeX within the bibliography database file.  The command

    @string{jgg1 = "Journal of Gnats and Gnus, Series~1"}

 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.

 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:

    @STRING{JgG1 = "Journal of Gnats and Gnus, Series~1"}

 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'.
3 Entry_format
      A bibliography database file  contains  a  series  of  reference
 entries like the following:

        @BOOK{kn:gnus,
            AUTHOR = "Donald E. Knudson",
            TITLE  = "1966 World Gnus Almanac",
            PUBLISHER = {Permafrost Press},
            ADDRESS = {Novisibirsk}             }

 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.

 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.

 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:

        @BOOK(kn:gnus,  author = {Donald E. Knudson},
                        TITLE  = "1966 World Gnus
                                        Almanac",
            PUBLISHER = {Permafrost Press},
            ADDRESS = {Novisibirsk}             )

 However, the case of letters does matter to LaTeX,  so  the  citation
 key ("kn:gnus" in the example above) should  appear  exactly the same 
 in all \cite commands in the LaTeX input file.

 The quotes or braces can be omitted around text  consisting  entirely
 of numerals.  the following two fields are equivalent:

                Volume = "27"           Volume = 27
3 Entry_types
 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.

 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:

 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.

 BibTeX ignores the case of letters in the entry type.
4 article_entry
      An article from a journal or magazine.

 Format:          @ARTICLE{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, journal, year
 Optional fields:  volume, number, pages, month, note, key
4 book_entry
      A book with an explicit publisher.

 Format:          @BOOK{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author or editor, title, publisher, year
 Optional fields:  volume, series, address, edition, month, note, key
4 booklet_entry
      A work that is printed and bound, but without a named  publisher
 or sponsoring institution.

 Format:          @BOOKLET{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  title
 Optional fields:  author, howpublished, address, month,  year,  note,
 key
4 conference_entry
      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.

 Format:          @CONFERENCE{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, booktitle, year
 Optional fields:  editor, pages,  organization,  publisher,  address,
 month, note, key
4 inbook_entry
      A part of a book, which may be  a  chapter  and/or  a  range  of
 pages.

 Format:          @INBOOK{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author or  editor,  title,  chapter  and/or  pages,
 publisher, year
 Optional fields:  volume, series, address, edition, month, note, key
4 incollection_entry
      A part of a book with its own title.

 Format:          @INCOLLECTION{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, booktitle, year
 Optional fields:  editor, pages,  organization,  publisher,  address,
 month, note, key
4 inproceedings_entry
      An article in the proceedings of a conference.

 Format:          @INPROCEEDINGS{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, booktitle, year
 Optional fields:  editor, pages,  organization,  publisher,  address,
 month, note, key
4 manual_entry
      Technical documentation.

 Format:          @MANUAL{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  title
 Optional fields:   author,  organization,  address,  edition,  month,
 year, note, key
4 mastersthesis_entry
      A Master's thesis.

 Format:          @MASTERSTHESIS{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, school, year
 Optional fields:  address, month, note, key
4 misc_entry
      Use this type when nothing else seems appropriate.

 Format:          @MISC{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  none
 Optional fields:  author, title, howpublished, month, year, note, key
4 phdthesis_entry
      A PhD thesis.

 Format:          @PHDTHESIS{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, school, year
 Optional fields:  address, month, note, key
4 proceedings_entry
      The proceedings of a conference.

 Format:          @PROCEEDINGS{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  title, year
 Optional fields:  editor, publisher,  organization,  address,  month,
 note, key
4 techreport_entry
      A report published by a school  or  other  institution,  usually
 numbered within a series.

 Format:          @TECHREPORT{citation_key,
                        required_fields [, optional_fields] }

 Required fields:  author, title, institution, year
 Optional fields:  type, number, address, month, note, key
4 unpublished_entry
      A document with an author and title, but not formally published.

 Format:          @UNPUBLISHED{citation_key,
                         required_fields [, optional_fields] }


 Required fields:  author, title, note
 Optional fields:  month, year, key
3 Field_text
 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.

 BibTeX manipulates the case of letters in the field text as described
 in the subtopics below.
4 Names
      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.

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

 Most names can be entered in the obvious way, either with or  without
 a comma, as in the following examples.

       "John Paul Jones"         "Jones, John Paul"
       "Ludwig von Beethoven"    "von Beethoven, Ludwig"

 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:

       "Brinch Hansen, Per"

 To understand why, you must understand how BibTeX handles names  (for
 what follows, a "name" corresponds to a person).

 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

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

 Here's another example:

       "Charles Louis Xavier Joseph de la Vallee 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.

 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:

       "{Barnes and Noble, Inc.}"
       "{Barnes and} {Noble, Inc.}"
       "{Barnes} {and} {Noble,} {Inc.}"

 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.

 So the two names

       "von Beethoven, Ludwig"   "{von Beethoven}, Ludwig"

 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.

 "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:

       "Ford, Jr., Henry"

 However, a few people do not  use  a  comma.   They  are  handled  by
 considering the "Jr." to be part of the last Last token:

       "{Steele Jr.}, Guy L."       "Guy L. {Steele Jr.}"

 This name has no Jr part.

 To summarize, you may type a name in one of three forms:

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

 If there are  multiple  authors  or  editors,  their  names  must  be
 separated  by  the  word "and", surrounded by spaces, not enclosed in
 braces:

       AUTHOR = "Ralph Alpher and Bethe, Hans and George Gamow"

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

 BibTeX's rules are actually a bit  more  complicated  than  indicated
 here, but this description will suffice for most names.
4 Titles
      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):

       TITLE  =  "The Agony and the Ecstasy"

 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.

       "The Gnats and Gnus of {Africa}"
       "The Gnats and Gnus of {A}frica"
4 Abbreviations
      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:

                        "  #  %  '  (  )  ,  =  {  }

 The abbreviation is typed in place of the text field, with no  braces
 or quotation marks.  If 'jgg1' is an abbreviation for

        Journal of Gnats and Gnus, Series~1

 then the following are equivalent:

        JOURNAL = jgg1
        JOURNAL = "Journal of Gnats and Gnus, Series~1"

 Some abbreviations are predefined by the bibliography  style.   These
 always  include the usual 3 letter abbreviations for the month:  jan,
 feb, mar etc.

 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.

 You can define your  own  abbreviations  by  using  BibTeX's  @STRING
 command.
3 Field_types
      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.

 BibTeX ignores the case of letters in the field names.
4 address_field
      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.

 Format:         ADDRESS = field_text
4 annote_field
      An annotation,  used  only  for  annotated  bibliography  styles
 (which are not among the standard ones).

 Format:         ANNOTE = field_text
4 author_field
      The name(s) of the author(s).

 Format:         AUTHOR = field_text
4 booktitle_field
      Title of a book, part of which is being cited.

 Format:         BOOKTITLE = field_text
4 chapter_field
      A chapter number.

 Format:         CHAPTER = field_text
4 edition_field
      The edition of a book - for example, "second".

 Format:         EDITION = field_text
4 editor_field
      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.

 Format:         EDITOR = field_text
4 howpublished_field
      How something strange has been published.

 Format:         HOWPUBLISHED = field_text
4 institution_field
      The institution that published the work.

 Format:         INSTITUTION = field_text
4 journal_field
      A journal name.  Abbreviations are provided for  many  journals;
 see the Local Guide.

 Format:         JOURNAL = field_text
4 key_field
      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.

 Format:         KEY = field_text
4 month_field
      The month in which the work was published or, for an unpublished
 work, in which it was written.

 Format:         MONTH = field_text
4 note_field
      Any additional information that can help the reader.

 Format:         NOTE = field_text
4 number_field
      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.

 Format:         NUMBER = field_text
4 organization_field
      The organization sponsoring a conference.

 Format:         ORGANIZATION = field_text
4 pages_field
      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.

 Format:         PAGES = field_text
4 publisher_field
      The publisher's name.

 Format:         PUBLISHER = field_text
4 school_field
      The name of the school where a thesis was written.

 Format:         SCHOOL = field_text
4 series_field
      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.

 Format:         SERIES = field_text
4 title_field
      The work's title.

 Format:         TITLE = field_text
4 type_field
      The type of a technical report - for example, "Research Note".

 Format:         TYPE = field_text
4 volume_field
      The volume of a journal or multivolume book work.

 Format:         VOLUME = field_text
4 year_field
      The year of publication or, for an unpublished work, the year it
 was written.  This field's text should contain only numerals.

 Format:         YEAR = field_text
2 bst_files
 Bibliography style files define the style of  a  bibliography  source
 list.

 The standard bibliography style files are  PLAIN,  UNSRT,  ALPHA  and
 ABBRV.

 If you want to make  a  bibliography  style  of  your  own,  look  at
 SAMPLE.BST.
3 ABBRV.BST
 This style is the same as the style defined in PLAIN.BST, except that
 entries are more compact because first names, month names and journal
 names are abbreviated.
3 ALPHA.BST
 This style is the same as the style defined in PLAIN.BST except  that
 entry labels like "Knu66", formed from the author's name and the year
 of publication, are used.
3 PLAIN.BST
 This style is formatted more or less as suggested by Mary-Claire  van
 Leunen  in  "A  Handbook  for  Scholars" (Alfred A.  Knopf, New York,
 1979).  Entries are  sorted  alphabetically  and  are  labelled  with
 numbers.
3 SAMPLE.BST
 This is a sample bibliography style file meant to help you  construct
 a  new  style.   It creates a bibliography in which entries appear as
 follows:

 [Jones79] Jones, R. L. and Richards, P. Q. The Birds and the Bees.
 {\it Journal of Irreproducible Results 4}, 2 (Jan. 1979), 27-33.

 [Jones82a] Jones, P. G. The Bees and the Trees ... (1982).

 [Jones82b] Jones, R. L. The Trees and the Peas ... (1982).

 [Krist74] Kristofferson, R. P. Peopl and Places ... (1974)

 It should illustrate how you write a style file.  The  functions  are
 described  in  an informal Pascal-like style in comments.  Because of
 the way while loops and if-then-else statements must  use  functions,
 the  following  convention is used.  If a while loop is labeled 'foo'
 in the informal description, then its test and body are the functions
 named  'foo.test'  and  'foo.body'.   If  an  if statement is labeled
 'foo', then its two clauses are the functions  named  'foo.then'  and
 'foo.else'.   (Null clauses just use the 'skip$' function.) Note that
 because functions have to be  defined  in  terms  of  already-defined
 functions, the actual function definitions are given in a 'bottom-up'
 order.
3 UNSRT.BST
 This style is that same as PLAIN.BST except that  entries  appear  in
 the order of their first citation.