doc/USD.doc/bibdoc.ms

..
 100
Reference File Formats
 0

A reference file is a file containing any number of reference
items. Reference items are separated by one or more blank lines.
There are no restrictions placed on the order of items in a file,
although imposing some order (such as sorting
items alphabetically) simplifies updates.

A reference item is a collection of field tags and values.
A field tag is a percent sign followed by a single letter.
Currently, the following field tags are recognized:
.Ex
A Author's name
B Title of book containing item
C City of publication
D Date
E Editor(s) of book containing item
F Caption
G Government (NTIS) ordering number
I Issuer (publisher)
J Journal name
K Keys for searching
N Issue number
O Other information
P Page(s) of article
R Technical report number
S Series title
T Title
V Volume number
W Where the item can be found locally
.QE

Author and editor fields can be repeated, as necessary, but all other fields
can occur at most once
in any reference. The field information is as long as necessary,
and can extend onto new lines.
Lines that do not begin with a percent sign or a period
are treated as continuations of the previous line.
The order of fields is irrelevant, except that authors and editors
are listed in the order of occurrence.

Generally a reference falls into one of several basic categories.
An example of each and a brief comment is given below. With less
standard references (Archival Sources, Correspondence, Government
Documents, Newspapers) generally some experimentation is necessary.
Books

A book is something with a publisher that isn't a journal article or
a technical report. Generally, books also have authors and titles
and dates of publication (although some don't). For books not published
by a major publishing house it is also helpful to give a city for the
publisher. Some government documents also qualify as books, so a book
may have a government ordering number.

It is conventional that the authors names appear in the reference in
the same form as on the title page of the book. Note also that
string definitions are provided for most of the major publishing houses
(PRHALL for Prentice-Hall, for example).
The string definition may include the city as part of the definition,
depending on the database in use.
.Ex
%A R. E. Griswold
%A J. F. Poage
%A I. P. Polonsky
%T The SNOBOL4 Programming Language
%I PRHALL
%D second edition 1971
.QE

Sometimes a book (particularly old books) will have no listed publisher.
The reference entry must still have an I field.
.Ex
%A R. Colt Hoare
%T A Tour through the Island of Elba
%I (no listed publisher)
%C London
%D 1814
.QE

If a reference database contains entries from many people (such
as a departmental-wide database), the W field can be used to indicate
where the referenced item can be found; using the initials of the owner,
for example.
Any entry style can take a W field, since this field is not used in
formatting the reference.

The K field is used to define general subject categories for an entry.
This is useful in locating all entries pertaining to a specific subject
area.
Note the use of the backslash, to indicate the last name is Van Tassel,
and not simply Tassel.
.Ex
%A Dennie Van\e\0Tassel
%T Program Style, Design, Efficiency,
Debugging and Testing
%I PRHALL
%D 1978
%W tab
%K testing debugging
.QE
Journal article

The only requirement for a journal article is that it have a
journal name and a volume number.
Usually journal articles also have authors, titles, page
numbers, and a date of publication. They may also have numbers, and,
less frequently, a publisher. (Generally, publishers are only listed for
obscure journals).

Note that string names (such as CACM for Communications of the ACM)
are defined for most major journals.
There are also string names for the months of the year, so that months
can be abbreviated to the first three letters.
Note also in this example the use of the K field to define a short
name (hru), that can be used in searching for the reference.
.Ex
%A M. A. Harrison
%A W. L. Ruzzo
%A J. D. Ullman
%T Protection in Operating Systems
%J CACM
%V 19
%N 8
%P 461-471
%D AUG 1976
%K hru
.QE
Article in conference proceedings

An article from a conference is printed as though it were a journal
article and the journal name was the name of the conference.
Note that string names (SOSP) are also defined for the major
conferences (Symposium on Operating System Principles).
.Ex
%A M. Bishop
%A L. Snyder
%T The Transfer of Information and Authority
in a Protection System
%J Proceedings of the 7th SOSP
%P 45-54
%D 1979
.QE
Article in book

An article in a book has two titles, the title of the article and the title
of the book. The first goes into the T field and the second into the B
field. Similarly the author of the article goes into the A field and the
editor of the book goes into the E field.
.Ex
%A John B. Goodenough
%T A Survey of Program Testing Issues
%B Research Directions in Software Technology
%E Peter Wegner
%I MIT Press
%P 316-340
%D 1979
.QE

If a work has more than one editor, they each get their own %E field.
.Ex
%A R. J. Lipton
%A L. Snyder
%T On Synchronization and Security
%E Richard A. DeMillo
%E David P. Dobkin
%E Anita K. Jones
%E Richard J. Lipton
%B Foundations of Secure Computation
%P 367-388
%I ACPRESS
%D 1978
.QE

Sometimes the book is part of a multi-volume series, and hence may
contain a volume field and/or a series name.
.Ex
%A C.A.R. Hoare
%T Procedures and parameters: An axiomatic approach
%B Symposium on semantics of algorithmic languages
%E E. Engeler
%P 102-116
%S Lecture Notes in Mathematics
%V 188
%I Springer-Verlag
%C Berlin-Heidelberg-New York
%D 1971
.QE

In any reference format, the O field can be used to give additional information.
This is frequently used, for example, for secondary references.
.Ex
%A A. Girard
%A J-C Rault
%T A Programming Technique for Software Reliability
%B Symposium on Software Reliability
%I IEEE
%C Montvale, New Jersey
%D 1977
%O (Discussed in Glib [32])
.QE
Compilations

A compilation is the work of several authors gathered together by an editor
into a book. The reference format is the same as for a book, with
the editor(s) taking the place of the author.
Note the word \*(oqeditors\*(cq has been added to the last author field.
.Ex
%A R. A. DeMillo
%A D. P. Dobkin
%A A. K. Jones
%A R. J. Lipton,\e\0editors
%T Foundations of Secure Computation
%I ACPRESS
%D 1978
.QE

Note: this will not work if names are to be reversed, because the
word "editors" will appear in the wrong place.
For this reason, bib has been modified (locally at Berkeley),
to accept editor entries anywhere author entries are legal.
Technical Reports

A technical report must have a report number. They usually have authors,
titles, dates and an issuing institution (the I field is used for this).
They may also have a city and a government issue number. Again string
values (UATR for \*(oqUniversity of Arizona Technical Report\*(cq) will
frequently simplify typing references.
.Ex
%A T. A. Budd
%T An APL Complier
%R UATR 81-17
%C Tucson, Arizona
%D 1981
.QE

If the institution name is not part of the technical report number, then
the institution should be given separately.
.Ex
%A Douglas Baldwin
%A Frederick Sayward
%T Heuristics for Determining Equivalence of Program Mutations
%R Technical Report Number 161
%I Yale University
%D 1979
.QE
PhD Thesis

A PhD thesis is listed as if it were a book, and the institution granting
the degree the publisher.
.Ex
%A Martin Brooks
%T Automatic Generation of Test Data for
Recursive Programs Having Simple Errors
%I PhD Thesis, Stanford University
%D 1980
.QE

Some authors prefer to treat Masters and Bachelor theses similarly, although
most references on style instruct say to treat a masters degree as an
article or as a report.
.Ex
%A A. Snyder
%T A Portable Compiler for the Language C
%R Master's Thesis
%I M.I.T.
%D 1974
.QE
Miscellaneous

A miscellaneous object is something that does not fit into any other form.
It can have any of the the following fields; an author, an editor,
a title, a date,
page numbers, and, most generally, other information (the O field).

Any reference item can contain an F field, and the corresponding text
will override whatever citation would otherwise be constructed.
.Ex
%F BHS--
%A Timothy A. Budd
%A Robert Hess
%A Frederick G. Sayward
%T User's Guide for the EXPER Mutation Analysis system
%O (Yale university, memo)
.QE
.bp

Reference Format Designers Guide

This section need only be read by those users
who wish to write their own formatting macro packages.

The information necessary for generating citations and references of a
particular style is contained in a format file. A format file
consists of two parts; a sequence of format commands, which are read and
interpreted by bib, and a sequence of text lines (usually troff macro
definitions) which are merely copied to output.
The format file name is always prefixed with the string bib.
Thus the format file for a standard document type, such as stdn, is found
in /usr/lib/bmac/bib.stdn.

When bib encounters a -t switch, the user's directory is first searched for
a format file matching the given name, before the system area is examined.
Thus the user can create individual style database files.

Each formatting command is distinguished by a single
letter, which must be the first character on a line.
The formatting commands in a database file are similar to the command line options
for bib. The legal commands,
and their arguments, are as follows:
# text

A line beginning with a sharp sign is a comment, and all remaining text on the
line is ignored.
A

The A command controls how authors' names are to be formatted.
It can be followed by the following character sequences:
 A
Authors names are to be abbreviated.
(See abbreviations below).
 Rnum
The first num authors names are to be reversed.
If num is omitted, all authors names are reversed
(i.e. T. A. Budd becomes Budd, T. A.).
 X
Authors names are to be printed in Caps-Small Caps style
(i.e., Budd becomes B\s-2UDD\s+2).

E

The E command is equivalent to the A command, except that it controls the
formatting of editors names.
F

The F command indicates that references are to be dumped immediately after
a line containing a citation, such as when the references are to be placed
in footnotes.
S template

The S command indicates references are to be sorted before being dumped.
The comparison used in sorting is based on the template. See
the discussion on sorting (below) for an explanation of templates.
C template

The template is used as a model in constructing citations.
See the discussion below.
D \0word \0definition

The word-definition pair is placed into a table.
Before each reference is dumped it is examined for the
occurrence of these words. Any occurrence of a word from this table is replaced
by the definition, which is then rescanned for other words.
Words are limited to alphanumeric characters, ampersand and underscore.

Definitions can extend over multiple lines by ending lines with a backslash
(\e). The backslash will be removed, and the definition, including the newline
and the next line,
will be entered into the table. This is useful for including several
fields as part of a single definition (city names can be included as part
of a definition for a publishing house, for example).
I filename

The indicated file is included at the current point. The included file may
contain other formatting commands.
H

Three or more contiguous citations that refer to adjacent items in the
reference list are replaced by a hyphenated string. For example, the
citation 2,3,4,5 would be replaced by 2-5. This is most useful with
numeric citations. The H option implies the O option.
O

Contiguous citations are sorted according to the order given by the reference
list.
T str

The str is a list of field names. Each time a definition string for
a named field is produced, a second string containing just the last character
will also be generated. See \*(oqTrailing characters\*(cq, below.

The first line in the format file that does not match a format command
causes that line, and all subsequent lines, to be immediately copied to
the output.
File Naming Conventions

Standard database format files are kept in a standard library area,
typically /usr/lib/bmac. There are three types of files:
 bib.xxx 10m
These files contain bib commands to format documents in the xxx style.
 bibinc.xxx
These files contain information (such as definitions) used by more than one
style database.
 bmac.xxx
These files are the troff macros to actually implement a style.
They are generally not examined by bib at all, but are processed
by troff in response to a .so command.
Naming Conventions

There is a simple naming convention for strings, registers and macros used
by bib. All strings, registers and macros are denoted by two character
names containing either a left or right brace. The following are general rules:
 [x
If x is alphnumeric, the string contains the value of a reference field.
If x is nonalphanumeric, this is a formatting string preceding a citation.
 ]x
If x is alphanumeric, this is the final character from a reference field.
If x is nonalphnumeric, the string is formatting information within a citation.
 x[
Strings in this format, where x is can be any character, are defined by the
specific macro package in use and are not specified by bib.
 x]
If x is nonalphanumeric these strings represent formatting commands following
citations (the inverse of [x commands). Other strings represent
miscellaneous formatting commands,
such as the space between leading letters in abbreviated names.
Sorting

The sort template is used in comparing two references to generate
the sorted reference list. The sort template is a sequence of
sort objects. Each sort object consists of an optional negative sign, followed
by a field character, followed by an optional signed size. The leading negative
sign, if present, specifies the sort is to be in decreasing order, rather than
increasing. The field character indicates which field in the reference
is to be compared. The entire field is used, except in the case of the `A'
field, in which case only the senior authors last name is used.
If the author's name is the sort key, and a particular reference has
no author field, then first the editor's name, then the %F field,
and then the institution is tried, looking for a usable sort key.
A positive number following the field character indicates that only the first
n characters are to be examined in the comparison. The negative value indicates
only the last n characters. Thus, for example, the template AD-2 indicates
that sorting is to be done by the senior author followed by the last two
characters of the date.

The sort algorithm is stable, so that two documents which compare equally
will be listed in citation order.
Citations

A citation template is similar to a sort template, with the following
exceptions: The field name \*(oq1\*(cq refers to the number which
represents the position of the reference in the reference list (after sorting).
The field name \*(oq2\*(cq generates a three character sequence; If the
paper being referenced has only one author, this is the first three characters
of the authors last name. For two author papers, this is the first two
characters of the senior author, followed by the first character of the second
author. For papers with three or more authors the first letter of the first
three authors is used.
Finally each object can be followed by either of the letters `u' or
`l' and the field will be printed in all upper or all lower case,
respectively.

If necessary for disambiguating, the character \*(oq@\*(cq can be used as
a separator between objects in the citation template. Any text which should
be inserted into the citation uninterpreted should be surrounded by either
{} or <> pairs.
Citation Formatting

In the output, each citation is surrounded by the strings \e*([[ and \e*(]]
(\e*([{ and \e*(}] in the alternative style).
Multiple citations are separated by the string \e*(],.
The text portion of a format file should contain troff definitions for
these strings to achieve the appropriate typographic effect.

Citations that are preceded by a period, comma or space are, in addition,
surrounded by the string values \e*([. and \e*(.] or \e*([, and \e*(,]
or \e*([< and \e*(>].
Again, troff commands should be given to insure the appropriate values are
produced.
.KS

The following table summarizes the string values that must be defined
to handle citations.


[[ ]] Standard citation beginning and ending
{[ }] Alternate citation beginning and ending
[. .] Period before and after citation
[, ,] Comma before and after citation
[? ?] Question mark before and after citation
[: :] Colon before and after citation
[; ;] Semicolon before and after citation
[! !] Exclamation mark before and after citation
[" "] Double quote before and after citation
[' '] Single quote before and after citation
[< >] Space before and after citation
], Multiple citation separator
]- Separator for a range of citations

.KE
Reference Formatting

The particular style used in printing references is decided by macros
passed to troff. Basically, for each reference,
bib generates a sequence of string definitions, one for each field in the
reference, followed by a call on the formatting macro. For example an
entry which in the reference file looks like:
.KS
%A M. A. Harrison
%A W. L. Ruzzo
%A J. D. Ullman
%T Protection in Operating Systems
%J CACM
%V 19
%N 8
%P 461-471
%D 1976
%K hru
.KE

is converted into the following sequence of commands
.KS
 .[-
 .ds [F 1
 .ds [A M. A. Harrison
 .as [A \e*(c]W. L. Ruzzo
 .as [A \e*(m]J. D. Ullman
 .ds [T Protection in Operating Systems
 .ds [J Communications of the ACM
 .ds [V 19
 .ds [N 8
 .nr [P 1
 .ds [P 461-471
 .ds [D 1976
 .][
.KE

Note that the commands are preceded by a call on the macro \*(oq.[-\*(cq.
This can be used by the macro routines for initialization, for example to
delete old string values. The string [F is the citation value used
in the document.
Note that the string CACM has been expanded.

The strings c], n] and m] are used to separate authors. c] separates
the initial authors in multi-author documents (it is usually a comma
with some space before and after), n] separates authors in two author
documents (usually \*(oq and \*(cq), and m] separates the last two authors
in multi-author documents (either \*(oq and \*(cq or \*(oq, and \*(cq).

If abbreviation is specified, the string a] is used to separate initials
in the authors first name.

The bib system provides minimal assistance in
deciding format types. For example note that the number register [P has
been set of 1, to indicate that the article is on more than one page.
Similarly, in documents with editors, the register [E is set to the number
of editors.
Trailing Characters

There is a problem with fields that end with punctuation characters causing
multiple occurrences of those characters to be printed. For example, suppose
author fields are terminated with a period, as in T. A. Budd. If names
are reversed, this could be printed as Budd, T. A.. Even if names are not
reversed, abbreviations, such as in Jr. can cause problems.

To avoid this problem bib, if instructed, generates the last
character from a particular field as a separate string. The string name
is a right brace followed by the field character. Macro packages should
test this value before generating punctuation.
Abbreviations

The algorithm used to generate abbreviations from first names is fairly
simple: Each word in the first name field that begins with a capital
is reduced to that capital letter followed by a period.
In some cases, this may not be sufficient. For example, suppose
Ole-Johan Dahl should be abbreviated \*(oqO-J. Dahl\*(cq. The only
way to achieve this (short of editing the output) is to include troff commands
in the reference file that alter the strings produced by bib, as in the following
.QS
 ...
 %A Ole-Johan Dahl
 .ds [A O-J. Dahl
 ...
.QE

In fact, any troff commands can be entered in the middle of a reference
entry, and the commands are copied uninterpreted to the output.
For example, the user may wish to have a switch indicating whether the name
is to be abbreviated or not:
.QS
 ...
 %A Ole-Johan Dahl
 .if \en(i[ .ds [A O-J. Dahl
 ...
.QE
An Example

Figure 1 shows the format file for the standard alphabetic format.
The sort command indicates that sorting is to be done by senior author,
followed by the last two digits of the date. The citation template
indicates that citations will be the three character sequence described
in the section of citations
followed by the last two characters of the date (i.e. AHU79, for
example).
.KS
#
# standard alphabetic format
#
SAD-2
C2D-2
I /usr/lib/bmac/bibinc.fullnames
I /usr/lib/bmac/bibinc.std

Figure 1
.KE

The two I commands include two files. The first is a file of definitions
for common strings, such as dates and journal names. A portion of this
file is shown in figure 2.
Note that a no-op has been inserted into the definition string for
BIT in order to avoid further expansion when the
definition is rescanned.

The second file is a sequence of troff macros
for formatting the references. The beginning of this file is shown in figure 3.

On the basis of some simple rules (the presence or absence of certain fields)
the document is identified as one of five different types, and a call made
on a different macro for each type. This is shown in figure 4.

Finally figure 5 shows the macro for one of those different types, in this
case the book formatting macro.
.KS
# full journal names, and other names
#
# journals
D ACTA Acta Informatica
D BIT B\e&IT
D CACM Communications of the ACM
 ...
#
# months
#
D JAN January
D FEB February
 ...
D DEC December

Figure 2
.KE
.KS
 #
 # standard end macros
 #
 .ds [ [
 .ds ] ]
 .ds , ,
 .ds >. .
 .ds >, ,
 .ds c[ , \e&
 .ds n[ "" and \&
 .ds m[ , and \&
 ...
 .de p[ \e" produce reference beginning
 .IP [\e\e$1]\0\0
 ..
 .de [] \e" start displaying collected references
 .SH
 References
 .LP
 ..

Figure 3
.KE
.KS
 .de ][ \e" choose format
 .ie !"\e\e*([J"" \e{\e
 . ie !"\e\e*([V"" .nr t[ 1 \e" journal
 . el .nr t[ 5 \e" conference paper
 .\e}
 .el .ie !"\e\e*([B"" .nr t[ 3 \e" article in book
 .el .ie !"\e\e*([R"" .nr t[ 4 \e" technical report
 .el .ie !"\e\e*([I"" .nr t[ 2 \e" book
 .el .nr t[ 0 \e" other
 .\e\en(t[[
 ..

Figure 4
.KE
.KS
 ...
 .de 2[ \e" book
 .if !"\e\e*([F"" .p[ \e\e*([F
 .if !"\e\e*([A"" \e\e*([A,
 .if !"\e\e*([T"" \e\ef2\e\e*([T,\e\ef1
 \e\e*([I\ec
 .if !"\e\e*([C"" , \e\e*([C\ec
 .if !"\e\e*([D"" \e& (\e\e*([D)\ec
 \e&.
 .if !"\e\e*([G"" Gov't. ordering no. \e\e*([G.
 .if !"\e\e*([O"" \e\e*([O
 .]-
 ..

Figure 5
.KE
.rs
.bp
APPENDIX
Standard Names

The following list gives the standard names recognized in most
citation styles. Various different forms for the output are used
by the different styles.
Journal Names
ACTA Acta Informatica
BIT BIT
BSTJ Bell System Technical Journal
CACM Communications of the ACM
COMP Computer
COMPJOUR The Computer Journal
COMPLANG Computer Languages
COMPSUR ACM Computer Surveys
I&C Information and Control
IEEETSE IEEE Transactions on Software Engineering
IEEETC IEEE Transactions on Computers
IPL Information Processing Letters
JACM Journal of the ACM
JCSS Journal of Computer and System Sciences
NMATH Numerical Mathematics
SIAMJC Siam Journal on Computing
SIGACT SIGACT News
SIGPLAN SIGPLAN Notices
SIGSOFT Software Engineering Notes
SP&E Software - Practice & Experience
TODS ACM Transactions on Database Systems
TOMS ACM Transactions on Mathematical Software
TOPLAS ACM Transactions on Programming Languages and Systems
Conferences
POPL ACM Symposium on Principles of Programming Languages
POPL5 Conference Record of the Fifth POPL
POPL6 Conference Record of the Sixth POPL
POPL7 Conference Record of the Seventh POPL
POPL8 Conference Record of the Eighth POPL
POPL9 Conference Record of the Ninth POPL
POPL10 Conference Record of the Tenth POPL
STOC Annual ACM Symposium on Theory of Computing
FOCS Annual Symposium on Foundations of Computer Science
ICSE International Conference on Software Engineering
SOSP Symposium on Operating System Principles
JICAI Joint International CONF on Artifical Intelligence
Publishers
ACPRESS Academic Press
ACADEMIC Academic Press
ADDISON Addison Wesley
CSPRESS Computer Science Press
ELSEVIER American Elsevier
FREEMAN W. H. Freeman and Company
MCGRAW McGraw-Hill
MITP M. I. T. Press
PRHALL Prentice Hall
SPRINGER Springer Verlag
WILEY John Wiley & Sons
WINTH Winthrop Publishers
Months of the year
JAN January
FEB February
MAR March
APR April
MAY May
JUN June
JUL July
AUG August
SEP September
OCT October
NOV November
DEC December
Misc
PROC Proceedings
CONF Conference
SYMP Symposium
DISS Dissertation
DEPT Department
UNIV University
CSD Computer Science Department
DCS Department of Computer Science
UATR University of Arizona Technical Report