BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



NAME
     bibtex - make a LaTeX bibliography

SYNOPSIS
     bibtex auxname

DESCRIPTION
     Bibtex reads the top-level auxilliary (.aux) file output
     during the running of latex (1) and creates a bibliography
     (.bbl) file that can be included in the LaTeX source file.
     The auxname on the command line should be given without an
     extension.  Each \cite in the source file is looked up in
     bibliography files to gather together those used in the
     document.  Then a bibliography style file is executed to
     write a \thebibliography environment.

     The source file should have defined the bibliography (.bib)
     files to search with the \bibliography command, and the
     bibliography style (.bst) file to execute with the
     \bibliographystyle command.  Bibtex incorporates the path
     searching mechanism described in the manual page for tex
     (1). It searches the TEXINPUTS path for .aux, .bbl, and .bst
     files.

     Eventually there will be a section in the LaTeX manual
     describing the bibliography and bibliography style formats.
     For now, here are brief descriptions.


Bibliography File
     The bibliography file (.bib) format is just about a subset
     of that allowed in Scribe bibliographies.  Only the delim-
     iter pairs {...} and "..." are allowed inside entries.
     Entries themselves can be delimited by (...) also.  The =
     sign between field names and field values is not optional.

     There are a number of conventions that should be followed
     when writing .bib files.  These are not requirements of bib-
     tex, but standard bibliography style files will typically
     expect these conventions to be followed.

     References should be categorized as in Scribe into one of
     the categories: article, book, booklet, inbook, incollec-
     tion, inproceedings, manual, mastersthesis, misc, phdthesis,
     proceedings, techreport, and unpublished.  See the Scribe
     manual for the fields that must/can appear in each type of
     reference.

     The title field should be entered in uppers-and-lowers for-
     mat, where everything is capitilized except articles and
     unstressed conjunctions and prepositions, and even those are
     capitilized if they are the first word or the first word



Printed 10/11/89                                                1






BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



     after a colon.  Some style files will convert all words
     except the first to all lowercase.  This is a mistake for
     things like proper nouns, so you have to tell bibtex not to
     touch such capital letters by enclosing them in braces, as
     in "Dogs of {A}merica".  It is unlikely that any style file
     would attempt to convert book titles to lowercase, so
     perhaps you can omit braces in such titles.

     The author and editor fields should conform to a particular
     format, so that the style file can parse them into parts.  A
     name can have four parts: first, von, last, junior, each of
     which can consist of more than one word.  For example, "John
     Paul von Braun, Jr." has "John Paul" as the first part,
     "von" as the von part, "Braun" as the last part, and "Jr."
     as the junior part.  Use one of these formats for a name:
          First von Last
          von Last, First
          von Last, Junior, First
     The last part is assumed to be one word, or all the words
     after the von part.  Bibtex will treat anything in braces as
     one word, so use braces to surround last names that contain
     more than one word.  The von part is recognized by looking
     for words that begin with lowercase letters.  When possible,
     enter the full first name(s);  style files may abbreviate by
     taking the first letter.  Actually, the rules for isolating
     the name parts are a bit more complicated, so they do the
     right thing for names like "de la Grand Round, Chuck".
     There is no need for a field like Scribe's fullauthor field.

     If there are multiple authors or editors, they should all be
     separated by the word and.  Scribe's editors field should
     not be used, since bibtex style files can count how many
     names are in an editor field.


Bibliography Style File
     Style (.bst) files are written in a postfix stack language.
     A dedicated hacker can probably figure out how to program in
     it by looking at an existing style file.  The following
     descriptions of builtin functions may help.  in the descrip-
     tions, "first", "second", etc., refer to the order popped.

     +    Pop the top two (integer) literals and push their sum.

     -    Pop the top two (integer) literals and push their
          difference (the first subtracted from the second).

     >    Pop the top two (integer) literals, compare them, and
          push the integer 1 if the second is greater than the
          first, 0 otherwise.

     <    Pop the top two (integer) literals, compare them, and



Printed 10/11/89                                                2






BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



          push the integer 1 if the second is less than the
          first, 0 otherwise.

     =    Pop the top two (integer or string) literals, compare
          them, and push the integer 1 if they're equal, 0 other-
          wise.

     *    Pop the top two (string) literals, concatenate them (in
          reverse order, that is, the order in which pushed), and
          push the resulting string back onto the stack.

     :=   Pop the top two literals and assign to the second the
          value of the first.  Integer and string variables can
          be declared with "INTEGERS {i1 i2 ...}" and "STRINGS
          {s1 s2 ...}", respectively.

     add.period$
          Pop the top (string) literal, add a period to it if the
          last non-right-brace character isn't a period, question
          mark, or exclamation-mark, and push this resulting
          string back onto the stack.

     call.type$
          Execute the function corresponding to the reference
          classification of the current entry.  For example, when
          processing an @INBOOK entry, call the "inbook" function
          if it is defined, otherwise call the "default.type"
          function.  Functions are declared with the FUNCTION
          command: the first argument is the function name and
          the second is the body.  An ENTRY command declares the
          variables that may be used in the style file when pro-
          cessing an entry.  It has three brace-surrounded argu-
          ments: a list of field names that may occur in the
          entry (these are read-only variables returning the
          value assigned to the fields in the current entry), a
          list of local integer variables, and a list of local
          string variables.

     change.case$
          Pop the top two (string) literals; change the case of
          the second according to the specifications of the
          first, as follows.  (Note: The word `letters' in the
          next sentence refers only to those at brace-level 0,
          the top-most brace level; no other characters are
          changed.)  If the first literal is the string ul, con-
          vert all letters to lower case except the very first
          character in the string, which should be converted to
          upper case; if it's the string uu, convert all letters
          to upper case; if it's the string ll, convert all
          letters to lower case; if it's the string lu, convert
          all letters to upper case except the very first charac-
          ter in the string, which it converts to lower case.



Printed 10/11/89                                                3






BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



          Then push this resulting string.

     chr.to.int$
          Pop the top (string) literal, make sure it's a single
          character, convert it to the corresponding ASCII-code
          integer, and push that integer.

     cite$
          Push the string used in a cite of the current entry
          (i.e., the codeword that appears at the beginning of
          the entry).

     duplicate$
          Push a duplicate of the stack top onto the stack.

     format.name$
          Pop the top three literals (they are a string, an
          integer, and a string literal, in that order).  The
          last string literal represents a name list (each name
          corresponding to a person), the integer literal speci-
          fies which name to pick from this list, and the first
          string literal specifies how to format this name.  Push
          the formatted name.  The first string literal should be
          something like "{ff }{vv }{ll}{, jj}", or "{vv }{ll}{,
          jj}{, f}". In such a string, an f stands for the first
          name part, a v stands for the von part, etc.  The dou-
          bled letters mean "put the whole part here" and the
          single letters mean "put an abbreviation (first
          letter(s)) here".  These formatting letters should
          occur at brace level 1.  If any of the corresponding
          parts of the name is missing, everything in the brace
          group corresponding to that part is omitted.

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

     int.to.chr$
          Pop the top (integer) literal interpreted as the ASCII
          code of a single character, convert it to the
          corresponding single-character string, and push that
          string.

     int.to.str$
          Pop the top (integer) literal, convert it to its
          (unique) string equivalent, and push that string.

     missing$
          Pop the top literal and push the integer 1 if it's a
          missing field (the current entry didn't have an assign-
          ment for it), 0 otherwise.



Printed 10/11/89                                                4






BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



     newline$
          Write whatever has accumulated in the output buffer
          onto the .bbl file, followed by a newline character.

     num.names$
          Pop the top (string) literal; push the number of names
          the string represents: one plus the number of
          occurrences of the substring "and" surrounded by non-
          null white-space (ignoring case differences) at the top
          brace level.

     purify$
          Pop the top (string) literal, convert upper-case
          letters to lower case, remove nonalphanumeric charac-
          ters except for white-space characters (one or more
          consecutive ones get compressed to a single space), and
          push the resulting string.

     quote$
          Push the string consisting of the double-quote charac-
          ter.

     skip$
          Do nothing.

     stack$
          Pop and print the whole stack on the terminal and log
          file.

     substring$
          Pop the top three literals (they are the two integers
          literals len and start and a string literal, in that
          order).  Push the substring of the (at most) len con-
          secutive characters starting at the startth character
          (assuming 1-based indexing) if len is positive, and
          ending at the -startth character from the end if start
          is negative (where the first character from the end is
          the last character).

     swap$
          Swap the top two elements of the stack.

     top$ Pop and print the top of the stack on the terminal and
          log file.

     type$
          Push the reference classification type (book, article,
          etc.), of the current entry onto the stack (unless
          either it's empty or undefined, in which case push the
          null string).

     while$



Printed 10/11/89                                                5






BIBTEX(1)           UNIX Programmer's Manual            BIBTEX(1)



          Pop the top two (function) literals, and keep executing
          the second as long as the (integer) value left on the
          stack by executing the first is greater than 0.

     width$
          Pop the top (string) literal and push the integer that
          represents its width.  The width is currently calcu-
          lated in hundredths of a point, using the character
          widths of the amr10 font.  The only white-space charac-
          ter with non-zero width is the space.  However, the
          width returned should only be used in comparisons with
          other such widths.

     write$
          Pop the top (string) literal and write it on the .bbl
          file.


SEE ALSO
     latex(1), tex(1).

BUGS
     The cacm style file is really just a skeleton so far.

HISTORY
     Written by Oren Patashnik under the direction of Leslie Lam-
     port.  Ported to UNIX by Howard Trickey, June 1984.




























Printed 10/11/89                                                6





