V10/vol2/prefer/oprefer.m

|make(rp)

|insert(../monk/monk.mac)

|comment(VOL2HEADER)|set_counter(page 163-1)|set_string(page_headers "'''")|set_string(even_headers "'Formatting References with Prefer''\f(NIprefer\fP'")|set_string(odd_headers "'\f(NIprefer\fP''Formatting References with Prefer'")|set_string(even_footers "_\\nP__UNIX Papers_")|set_string(odd_footers "'Research Tenth Edition''\\nP'")
|author(name "M. A. Derr", initials MAD, location MH, department 11225,
	extension x4721, room 2D-455)

|date(July 1, 1989)
|title(Formatting References with Prefer)

|begin(abstract)
|i(Prefer) is a |small(UNIX) text processing
tool
that formats bibliographic references.
Using a bibliography database, it scans a document to
convert symbolic references
to citation marks and full references ready for typesetting.
It currently supports a variety of reference formatting
styles including those of the |s(ACM), |s(IEEE), and |s(APA).
|i(Prefer)
runs as a preprocessor to |i(troff)
and can also be invoked by
the |i(monk) text processing package.
This paper describes |i(prefer) and its supporting
tools for creating, indexing,
and retrieving from bibliography databases and for
converting |i(refer)-style databases and documents
for use with |i(prefer).
|end(abstract)


|titlebox

|insert(prefer.cite)

|style(two_column)

|section(Introduction)

|i(Prefer) is a |small(UNIX) text processing
tool|dagnote[in addition to
Tenth Edition |small(UNIX),
|i(prefer) runs under
|small(AT&T UNIX) System V
and 4.3|small(BSD UNIX).]
that formats bibliographic references.
Using a bibliography database, it scans a document to
convert symbolic references
to citation marks and full references ready for typesetting.
Like |i(eqn)|reference(latest eqn) and
|i(tbl)|reference(latest tbl), |i(prefer)
runs as a preprocessor to |i(troff)
|reference(latest troff tutorial).
It can also be invoked by
the |i(monk)|reference(latest monk) text processing package.

|p
|i(Prefer) was designed to replace the |i{refer}
|reference{Lesk indexes} bibliography program.
|i(Refer) is not only lacking in flexibility, with much of
its functionality hardwired into C code,
but the code is difficult to modify and maintain.
|i(Prefer) improves on
|i{refer} and
on |i{bib} |reference{bib}, an earlier
|i{refer} replacement.
It also follows style conventions found in
other bibliography formatters such as |i{Scribe} |reference{scribe},
and |i{BibTeX} |reference{latex} |reference{bibtex}.
It attains flexibility by encoding all style-dependent formatting
information in scripts written in |i{awk} |reference{awk 1988},
a pattern scanning and processing language.
|i{Prefer} currently supports seven reference formatting styles:

|begin(bullet_list)
|item |cw(att) \- used at |small(AT&T) Bell Laboratories
|item |cw(acm) \- Association for Computing Machinery
|item |cw(apa) \- American Psychological Association
|item |cw(ieee) \- Institute of Electrical and Electronics Engineers, Inc.
|item |cw(lsa) \- Linguistic Society of America
|item |cw(pami) \- Pattern Analysis and Machine Intelligence
|item  |cw(spectrum) -\ |small(IEEE) Spectrum
|end(bullet_list)
In addition, users may define their own styles
by supplying an appropriate |i{awk} style script.
|i{Prefer} uses the |cw{att} style by default.
Unless noted, all examples in this paper will be
in |cw{att} style.

|p
To give a flavor of what |i(prefer) can do, here is
a simple example of a document containing citations to
references in a bibliography database.
At the end of the document, the full references are printed.
Here's the document before it is formatted:

|begin(here)
|begin(figure)
|begin(small)
|insert(example/simple.in)
|end(small)
|end(figure)
|end(here)

The command |cw<|sp(|s)reference(awk)> tells |i(prefer)
to search a bibliography database for a reference containing
the word ``awk,'' somewhere
in a database entry, e.g, in the author or title field.
|i(Prefer) will replace
the |cw<|sp(|s)reference>
command with a citation mark that corresponds
to the matching reference.
References from each |cw<|sp(|s)reference>
command are remembered by |i(prefer).
When |i(prefer) reaches the |cw<|sp(|s)reference_placement>
command, references seen so far are formatted
according to the current style.
When the above document (in a file called
|cw(document)) is run through |i(prefer)
and |i(troff):

|figure<|small{|cw(prefer document | troff) |i(-options) |cw(...)}>

the following output is produced:

|p
|begin(here)
|begin(small)
|source(example/simple.t)
|end(small)
|end(here)

|p
In addition to the |i{prefer} program,
several other support tools are available.
|i(Penter)
is an interactive tool for creating
or appending to bibliography databases.
|i(Pinvert) creates an index to the bibliography database for fast retrieval.
|i(Plook) retrieves entries that match search keywords
from a bibliography database.
|i(Pconvert) converts |i(refer)-style documents and databases to
|i(prefer)-style.
The remainder of this
paper describes |i(prefer) and its supporting tools
and provides
examples of their use.

|section(Bibliographic Database)
A bibliography database is a file consisting of
one or more entries separated by newlines.
Each entry is composed of several %attribute/value pairs
providing such information as type, author, title, and date.
For example, here is an entry describing the |i(awk) book
referenced in the previous example.

|begin(here)
|begin(figure)
|begin(small)
%type book
%author Alfred V. Aho
%author Brian W. Kernighan
%author Peter J. Weinberger
%title The |small(AWK) Programming Language
%publisher Addison-Wesley
%address Reading, Massachusetts
%date 1988
|end(small)
|end(figure)
|end(here)

Appendix |remember{types}
provides a complete list of types and
attributes.

|subsection{Building a Bibliography}
You may create or modify a bibliography database using your
favorite text editor or by using the tool,
|i{penter}.|starnote<|i(Penter) is based on a program
written by T.J. Kowalski and H. H. Goguen.>
After invoking |i{penter} with the name of the bibliography file
as the argument (|cw[prefer.out] by default),
|i{penter} prompts for a reference type.
Typing |cw<?> to this prompt
gets you a list of legal types.
Typing |cw<help> to the same prompt will get
you a subprompt for a reference type who's attributes
will be listed.  Answering |cw<?> to this subprompt
will list attributes for each type.
|p
Each reference type has some required attributes and some optional
attributes.
After you respond to the initial reference type prompt
with a legal type, |i(penter) prompts for each
attribute associated with that type.
Some attributes have
default values, shown in  brackets, |cw([) |i(default) |cw(]).
Defaults may be accepted
by typing a return, skipped by typing spaces before
the return, or overridden by typing a new value.
For attributes without defaults,
typing a value followed by return
enters that value, while typing return, skips the attribute.
Required attributes may not be skipped.
The character |cw<&> appended to an attribute value
causes the prompt for the current attribute to be repeated.
This allows multiple authors or editors to be entered
or allows titles to span multiple lines, for example.
|p
When |i{penter} is finished with an entry, it
begins again, prompting for another reference type.
To terminate a |i{penter} session, type |cw<quit> and
the new entries will be written to the bibliography file.
This example shows how to enter the previous reference
using |i(penter); the result is put in the file |cw(prefer.out).
|i(Penter)'s prompts are in |i(italics).

|begin(here)
|begin(figure)
|begin(small)
|cw(penter)
|i(Reference type [article]) |cw(book)
|i(author:) |cw(Alfred V. Aho&)
|i(author:) |cw(Brian W. Kernighan&)
|i(author:) |cw(Peter J. Weinberger)
|i(title:) |cw(The AWK Programming Language)
|i(publisher:) |cw(Addison-Wesley)
|i(date: 1988)
|i(volume:)
|i(other:)
|i(also:)
|i(keywords:)
|i(location status [don't have]:)
|i(read status [haven't read]:)
|i(comments:)
|i(Reference type [article]) |cw(quit)
|end(small)
|end(figure)
|end(here)
.............
|p
If you want to modify
the current entry,  respond to the current prompt with |cw<~v>
to invoke a visual editor (|cw($VISUAL)
if set, or |i(vi) if not)
or |cw<~e> to invoke
a line editor (|cw($EDITOR) if set, or |i(ed) if not).
After making some changes and
leaving the editor, you will be back in |i{penter} at the same
point where you left off.
Alternatively, you can modify the bibliography
file with a text editor after you have exited |i(penter).

|subsubsection(Author and editor names.)
Proper names may be entered in a variety of ways;
|i(prefer) knows how to figure out first names, initials, last names,
titles, etc.
It also knows about some two part last names such as
De Paul and Van Winkle.
For example, any of the following are acceptable ways to enter
a name.

|begin(here)
|begin(figure)
|begin(small)
%author John Thomas De Paul
%author Dr. John T. De Paul, Jr.
%editor J. T. De Paul Jr.
%editor De Paul, John T., Jr
|end(small)
|end(figure)
|end(here)
|p
If you use the name of an organization or
corporation as an author or editor and do
not want |i(prefer) to parse it as the name
of a person, enclose the name in the |cw(%verbatim) command.
This command is also useful in keeping
double last names together.
Here are two examples:
|begin(here)
|begin{figure}
|begin(small)
%author %verbatim(|small[AT&T] Bell Laboratories)
%author John %verbatim(Smith Jones)
|end(small)
|end{figure}
|end(here)

|subsubsection(The \f(CW%also\fP attributes.)

Another class of attributes deserves special mention.
The |cw(%also) attributes allow one bibliographic reference
to refer by keyword to another reference contained in the
same database as this example shows:

|comment(replace this reference with something more relevant and shorter; maybe put formatted version in examples section)
|begin(here)
|begin(figure)
|begin(small)
|insert(example/hirst)
|end(small)
|end(figure)
|end(here)

When a reference to the first entry is formatted,
both references will appear in a single entry.
|begin(here)
|begin(small)
|source(example/hirst.t)
|end(small)
|end(here)

|p
Two other attributes,
|cw(%also_begin) and |cw(%also_end), can enclose
another |cw(%also) attribute, surrounding it with optional text
as this example demonstrates:
|begin(here)
|begin(figure)
|begin(small)
%also_begin (See also
%also Grosz Sparck Jones Webber
%also_end )
|end(small)
|end(figure)
|end(here)
Alternatively, a partial or complete reference may be included between
|cw(%also_begin) and |cw(%also_end):

|begin(here)
|begin(figure)
|begin(small)
%also_begin Reprinted in
%type editedbook
%title Programming Languages: A Grand Tour
%editor Ellis Horowitz
%date 1983
%publisher Computer Science Press
%address Rockville, MD
%also_end
|end(small)
|end(figure)
|end(here)
While |cw(%also) is supported by |i{penter},
|cw(%also_begin) and |cw(%also_end) are not and must
be entered using a text editor.
.......

|subsection(Indexing a Bibliography)

|i(Pinvert)|dagnote<Based on the |i(bib)|reference(bib) version
by T. A. Budd>
creates a search key
index to one or more bibliography database files.
Indexing the database lets you refer to any
entry using a unique combination of search keys.
To create the index, |i(pinvert) uses words of at least
three characters found the bibliography.
Some common words (those found in |cw</usr/lib/eign>)
are ignored.
In addition, values of some of the attributes
are ignored (|cw(%volume) and |cw(%pages), for example).
|i(Pinvert) converts all keys to lower case, removes
non-alphanumeric characters, and truncates
each key to six characters.
|p
|i(Pinvert) with no arguments, assumes that the bibliography
file is |cw(prefer.out) and stores the index and header information in
|cw(prefer.out.i) and |cw(prefer.out.h).
If more than one file is being indexed,
the index is named after the first file
in the list.
For example,

|figure<|small(|cw{pinvert ourbib theirbib mybib})>

creates an index to all three bibliography files,
storing the index and header information
in |cw(ourbib.i) and |cw(ourbib.h), respectively.
Alternatively, index and header files can also be given a
unique name using
the |cw(-p) option:

|figure(|small<|cw{pinvert \-p index yours mine ours}>)

stores the index and header files
for the three bibliography files in |cw(index.i) and |cw(index.h).

|p
|i(Pinvert) provides several other options.

|begin(here)
|figure[|cw<\-c> |i(cfile)]
|blank_space(-1)
specifies a file
of common words, one per line,
to exclude as indexing keys
(default is |cw(/usr/lib/eign)).
|end(here)
|begin(here)
|figure[|cw(\-i) |i(ifile)]
|blank_space(-1)
specifies a file
of attributes, one per line,
to ignore while collecting
keys from database entries.
The default file,  |cw(/usr/lib/prefer/ignore),
contains the attributes |cw(%volume), |cw(%number),
|cw(%part), |cw(%pages), |cw(%also), |cw(%X), |cw(%Y), and |cw(%Z).
|end(here)
|begin(here)
|figure[|cw(\-k) |i(maxkey)]
|blank_space(-1)
specifies the maximum number
of search keys
collected per reference (default is 100 keys).
|end(here)
|begin(here)
|figure[|cw(\-l) |i(keylen)]
|blank_space(-1)
specifies the maximum length of a search
key(default is 6 characters).
|end(here)
|begin(here)
|figure[|cw(\-v)]
|blank_space(-1)
tells |i(pinvert) to print statistics.
|end(here)

|blank_space(1)
|subsection<Retrieval by Keyword>

|i(Plook) is a command that uses an index
to search a bibliography database for references
that match search keys.
As in |i(pinvert),
search keys are a sequence of non-white space characters
with non-alphanumeric characters removed. 
Keys must be at least three characters and are
converted to lower-case and truncated to six characters.
Some common words are ignored (those in the file |cw</usr/lib/eign>
by default).
If the search keys appear on the command line, |i(plook) retrieves
all references that contain all the search keys
and prints the references on
the standard output.
For example,

|figure<|small(|cw{plook awk book})>

would output:

|begin(here)
|begin(figure)
|begin(small)
|begin(i)
%type book
%author Alfred V. Aho
%author Brian W. Kernighan
%author Peter J. Weinberger
%title The AWK Programming Language
%publisher Addison-Wesley
%address Reading, Massachusetts
%date 1988
|end(i)
|end(small)
|end(figure)
|end(here)

If the command line contains no search keys,
then |i(plook) reads a line of standard input for search keys.
After returning the matching reference(s) it waits for
the next line of keys, terminating when it receives
an end-of-file character, <|b(control-d)>.
Here's an example of this mode of use:

|begin(here)
|begin(figure)
|begin(small)
|cw(plook)
|cw(lesk indexes)
|begin(i)
%type incollection
%author M. E. Lesk
%title Some Applications of Inverted Indexes
 on the UNIX System
%booktitle UNIX Programmer's Manual,
 Seventh Edition
%publisher Bell Laboratories
%address Murray Hill, NJ
%date January, 1979
%volume 2A
|end(i)

|cw(lesk tables)
|begin(i)
%type incollection
%author M. E. Lesk
%title TBL \- A program to format tables
%booktitle UNIX Text Editing & Phototypesetting
 Starter Package
%editor Claudine Tartanella
%publisher Computing Information Services,
 Bell Laboratories
%address Murray Hill, NJ
%date 1980
|end(i)

|cw(<control-d>)
|end(small)
|end(figure)
|end(here)

|p
|i(Plook)
recognizes the options |cw<-c>, |cw<-l>, and |cw<-p>
with the same meanings as |i(pinvert).
If the index file is out of date or does not exist,
|i(plook) will try to create it by invoking |i(pinvert).

|section(Formatting References In Documents)

This section explores in detail the |i(prefer) program
for formatting documents with bibliographic references.
|i(Prefer) scans a text file looking for one
of the following commands to process:

|begin(here)
|begin(figure)
|cw<|sp(|s)reference( |i[keywords... attributes... flags...] )>
|cw<|sp(|s)reference_placement>
|cw<|sp(|s)reference_include( |i[dbfile...] )> 
|cw<|sp(|s)reference_database( |i[dbfile] )> 
|cw<|sp(|s)reference_list( |i[dbfile...] )>
|cw<|sp(|s)reference_style( |i(style [arg...] ))>
|end(figure)
|end(here)

Each will be described in turn.
The parentheses enclosing the command arguments
may be replaced by the |cw({}), |cw([]), or |cw(<>).
|i(Prefer) also accepts several command line options
that are explained at the end of this section.

|subsection(Citations)

The |cw<|sp(|s)reference>
command is for citing reference within a text.
As you saw in the introduction and in the
following example, you can cite a reference using
keywords which |i(prefer) will use
to search a bibliography database for a matching entry.

|figure<|small[|cw{... sort methods|reference(Knuth Art 1973) ...}]>

Keywords should be chosen so as to uniquely identify
a particular reference.
You can use words from any attribute
not ignored by |i(pinvert), including
|cw(%author), |cw(%title), |cw(%keyword) and |cw(%date).
If multiple references match the keys,
|i(prefer) will print a warning,
but use only the first match.
Similarly, if no references match, a warning message is printed.
If two or more references in the database share all possible search keys,
you can add extra words to the |cw(%keyword) attribute of each
entry in the database to
distinguish among them.

|p
In addition to keyword search, you can cite
a reference by including
the entire reference in the command as shown
below.
Note that subsequent references to this reference
will have to respecify all the attributes.
|begin(here)
|begin(figure)
|begin(small)
|sp(|s)reference(
%type book
%author Donald E. Knuth
%title The Art of Computer Programming
%volume Volume 3/Sorting and Searching
%publisher Addison-Wesley
%keywords sorting searching
%address Reading, MA
%date 1973
)
|end(small)
|end(figure)
|end(here)
|p
A third way is to use keywords to select a database reference,
followed by attributes
that supplement or override attributes
in the database reference.
For example, a keyword selected reference could
be supplemented with a |cw(%also) entry as shown below.
|begin(here)
|begin(figure)
|begin(small)
|sp(|s)reference(
McKeown phdthesis
%also_begin Also in
%type techreport
%publisher University of Pennsylvania
%date 1982
%report Technical Report MS-CIS-82-5
%also_end
)
|end(small)
|end(figure)
|end(here)
In all cases, |i(prefer)
replaces the citation command with
a citation mark that corresponds
to the full reference as it appears in the list
formatted by the |cw<|sp(|s)reference_placement>
command.
The |cw(att), |cw(ieee), and |cw(spectrum) styles
use superscripted numbers for citation marks;
|cw(acm) and |cw(pami) styles use numbers in square brackets;
|cw(apa) and |cw(lsa) styles use (author, year).

|p
Following keywords and attributes, you can supply
flags that
modify the citation mark.
The citation flags, |cw(%no_author) and |cw(%no_date),
relevant to |cw(att) and |cw(lsa) styles,
cause the author field and date field, respectively, to be excluded
from the citation mark.
The |cw(%no_cite) flag, relevant to all styles, causes the entire citation to be
omitted, but the full reference is still printed in the list of
references.
Some styles
let you annotate a citation with text
using |cw(%pre_text) and |cw(%post_text).
Annotations could include introductory phrases
and page numbers, for example.
If multiple citation flags are used (e.g, both |cw(%no_author)
and |cw(%post_text)),
each must appear on it's own line.
Formatting the following document fragment in |cw(apa) style
|begin(here)
|begin(figure)
|begin(small)
|insert(example/lamport.in)
|end(small)
|end(figure)
|end(here)
produces this output:
|begin(here)
|begin(figure)
|begin(small)
|source(example/lamport.t)
|end(small)
|end(figure)
|end(here)

More uses of |cw<|sp(|s)reference> are found in
Appendix |remember(examples).

|subsection(Reference Placement)


The |cw<|sp(|s)reference_placement> command causes all
references seen since the beginning of the document,
the last |cw<|sp(|s)reference_placement>,
or the last |cw<|sp(|s)reference_style> command,
to be formatted and inserted in the document at that point.
The order of references depends on the current style.
References in |cw(att), |cw(ieee), and |cw(spectrum) styles 
appear in the order first cited in the preceding text.
References in |cw(acm), |cw(apa), |cw(lsa), and |cw(pami) are sorted by
author, date, and title.
All except |cw(apa) and |cw(lsa)
have labels that match the citation
marks appearing in the text.
|p
See Appendix |remember(examples) for uses
and results of |cw<|sp(|s)reference_placement>.


|subsection(Including Additional References)
Sometimes you may want the reference list
to include more references than you actually
cite in the text.
The |cw<|sp(|s)reference_include( |i[dbfile...] )> command 
includes the contents of one or more database files
in the list of references produced by
|cw<|sp(|s)reference_placement>, treating
them as |cw(%no_cite) entries.
For example, the |cw<|sp(|s)reference_placement>
command here:

|begin(here)
|begin(figure)
|begin(small)
|i(text with citations)
...
|sp(|s)reference_include(morebibs)
|sp(|s)reference_placement
|end(small)
|end(figure)
|end(here)

will include in its list
of references all the entries in the file |cw(morebibs)
as well as 
any citations found in the text.

|subsection(Switching Databases)

The command to search a new bibliography database is
|cw<|sp(|s)reference_database( |i[dbfile] )>.
|i(Prefer) then closes the current
database file, and opens the new one, |i(dbfile).
But it still remembers citations from the previous
database.
For example, in

|begin(here)
|begin(figure)
|begin(small)
|sp(|s)reference_database(mybib1)
|i(text with citations)
...
|sp(|s)reference_database(mybib2)
|i(text with more citations)
...
|sp(|s)reference_placement
|end(small)
|end(figure)
|end(here)

the first database, |cw(mybib1),
is consulted for the first part of the text,
while the database |cw(mybib2) is consulted
for the second part.
The |cw<|sp(|s)reference_placement> command
will list citations from both databases.
|p
All databases should be indexed using |i(pinvert).
However, if a database has not been indexed since its last update,
|i(prefer) will automatically
invoke |i(pinvert) before using the database.

|subsection(Complete Bibliographies)

Beside formatting references appearing in documents,
|i(prefer) also formats entire bibliography databases.
The command |cw<|sp(|s)reference_list( |i[dbfile...] )>,
behaves like |cw<|sp(|s)reference_placement>
except that instead of formatting citations appearing
in the previous text, it formats
all the references appearing in one or more bibliography
databases.
For example,

|figure<|small[|sp(|s)reference_list(mybib88 mybib89)]>

produces a list of all references in the file |cw(mybib88)
followed by all references in |cw(mybib89).
|p
Like |cw<|sp(|s)reference_database>,
this command changes the search database.
The current style dictates how each entry will be formatted.
By default, the entries will be printed
in the order they appear in the database(s).
Changing this order requires
setting some style arguments or
supplying some command line options.
Both ways are described below.


|subsection(Styles Options)
|save(stylesec)
The |cw<|sp(|s)reference_style( |i(style [arg...] ))> command provides one way
to change options regarding formatting style.
The first argument to this command selects
the style script.
It gives the name of one of
the styles provided by prefer
(|cw(att), |cw(acm), |cw(apa), |cw(ieee), |cw(spectrum), |cw(lsa)
or |cw(pami)), or the pathname of
a user-defined style script.
Note that any file in the current directory with the same
name as one of the |i(prefer) styles (e.g. |cw(acm)),
will override the |i(prefer) style. 
The easiest way to define a new style is
to modify an existing |i{awk} style script that is similar
to the desired style.
Describing how to write a style script in further detail is
beyond the scope of this paper.
|p
Your document may use multiple formatting styles
by resetting the style using |cw<|sp(|s)reference_style>.
If you switch styles before issuing a |cw<|sp(|s)reference_placement>
command, the citations appearing before the style command
will be forgotten and thus,
will not be listed by any subsequent |cw<|sp(|s)reference_placement>.
|p
Some of the optional arguments to the style command control
how references
are formatted by the |cw<|sp(|s)reference_list> command.
|begin(here)
|begin(table)
center;
l l.
|cw(sequence)	list in database order
|cw(sort)	list according to current style
|cw(a)	sort by author
|cw(d)	sort by date
|cw(t)	sort by title
|end(table)
|end(here)
The last three options may be used in combination.
If optional arguments are given, but the
style is to remain the same, the first
argument may be set to |cw(same).
|p
The style command recognizes several other
arguments that affect the formatting of references.
These are:
|begin(here)
|begin(table)
center;
l l.
|cw(tm)	format as a technical memorandum
|cw(rp)	format as a released paper
|cw(troff)	format for |i(troff)
|cw(nroff)	format for |i(nroff)
|end(table)
|end(here)
The defaults are for a paper to be formatted
as a technical memorandum using |i(troff)
Here are some examples of using the style command:
|begin(here)
|begin(figure)
|begin(small)
|begin(cw)
|sp(|s)reference_style(/usr/mad/mystyle ad)
|sp(|s)reference_list(bib)
|sp(|s)reference_style(acm sort rp)
|sp(|s)reference_list(bib)
|sp(|s)reference_style(same sequence nroff)
|sp(|s)reference_list(bib)
|end(cw)
|end(small)
|end(figure)
|end(here)

The first command selects the user-defined style
in |cw(/usr/mad/mystyle) and says to sort according
to author, then date.
The bibliography file |cw(bib) is formatted accordingly.
The third command selects the |cw(acm) style,
and says to sort |cw(bib) according to that style.
It also say says to format it as a released paper.
The fifth command says to use the same style (|cw[acm]),
but this time print the references as they
appear in |cw(bib) and
format the paper using |i(nroff).


|subsection(Command Line arguments)

Command line arguments provide another way
to select bibliography databases and set style options.

|begin(here)
|figure[|cw(\-p) |i(dbfile)]
|blank_space(-1)
specifies a bibliography
database, |i(dbfile) (default is |cw(prefer.out))
|end(here)
|begin(here)
|figure[|cw(\-s) |i(sname)]
|blank_space(-1)
selects formatting style |i(sname)
(default is |cw(att)). The argument |i(sname)
names of one of the provided styles or
a user-defined style.
|end(here)
|begin(here)
|figure[|cw(\-o) |i(okey)]
|blank_space(-1)
specifies how
the |cw<|sp(|s)reference_list>
command should order references.
The argument |i(okey) may be one of
|cw(sequence) (the default), |cw(sort), or a combination of
|cw(a), |cw(d), or |cw(t), as described above in Section
|remember(stylesec).
|end(here)
|begin(here)
|figure[|cw(\-n)]
|blank_space(-1)
format using |i(nroff) rather than for |i(troff),
the default.
|end(here)
|begin(here)
|figure[|cw(\-r)]
|blank_space(-1)
format as
a released paper, rather than an
internal technical memorandum, the default.
|end(here)
For example, the command

|figure<|small[|cw{prefer -r -sacm -pmybib  mydoc}]>

processes |cw(mydoc) as a released paper, using |cw(acm) style
and the bibliography database |cw(mybib).

|section(Using |i<prefer> |b(With) |i<monk>)

As mentioned earlier, the |i(monk) text formatting package
invokes |i(prefer) to format bibliographic references.
To do this, it must convert its own reference commands to ones
understood by |i(prefer).
For the
|cw<|sp(|s)reference>,
|cw<|sp(|s)reference_list>,
and |cw<|sp(|s)reference_database>
commands, this is easy;
|i(monk's) versions are identical to |i(prefer's).
Note that |i(monk) uses angle brackets |cw(<>)
to enclose the |i(prefer)
command arguments.
Thus if angle brackets appear in any of the command
arguments, confusion may arise.

|p
The |cw<|sp(|s)reference_placement> command in |i(monk)
differs slightly from the |i(prefer) version, depending on
the |i(monk) document style.
For example, for technical memoranda
it causes a new page
to be printed and
the reference list to be headed by
a centered |small(|cw<REFERENCE>) title.

|p
|i(Monk) does not have a 
|cw<|sp(|s)reference_style> command.
Instead, it uses it's own |cw<|sp(|s)style> command
along with a |cw(reference) attribute/value pair.
For example, to change the reference style to |cw(ieee), use the
monk command

|figure<|small[|sp(|s)style(reference ieee)]>

To set any of the other options provided by the |i(prefer)
|cw<|sp(|s)reference_style> command,
use the |i(monk) |cw<|sp(|s)style> command
with a |cw(reference_option) attribute/value pair.
For example,

|figure<|small[|sp(|s)style(reference_option rp)]>

means format references for a released paper.
Other possible values for |cw(reference_option) are:
|cw(tm), |cw(troff), |cw(nroff), |cw(sort), |cw(sequence), and any
combination of the letters |cw(a), |cw(d), |cw(t).
These options have the same meanings as for
the |cw<|sp(|s)reference_style> command.
The command line options |cw<\-s>, |cw<\-o>, |cw<\-r>, and |cw<\-n>
of |i(prefer) are not set by |i(monk).
|i(Monk) uses the style command to set these options.

|p
|i(Monk) uses the file |cw</usr/lib/monk/prefs> as its default bibliography
database.
You can specify an alternative database
with the |cw(\-R) option, which |i(monk) translates to the |cw<\-p>
option for |i(prefer).
For example,

|figure<|small(|cw{monk \-Rmybib mydoc})>

says that monk should use the file |cw(mybib)
as the bibliography database when formatting |i(mydoc).

|section(Converting From |i<refer> |b(To) |i<prefer> )

The |i(pconvert) command converts a |i(refer) style bibliography
database
to |i(prefer) format.
For example, the command

|figure<|small(|cw{pconvert refer.out > prefer.out})>

scans the file |cw(refer.out) and writes the transformed version
into |cw(prefer.out).
|i(Pconvert) uses the attributes of each
entry to infer the |cw(%type) of the entry.

|p
With the |cw(\-d) option |i(pconvert)
changes |i(refer) style commands in a document
to |i(prefer) style.
For example

|figure<|small(|cw{pconvert \-d oldpaper > newpaper})>

scans |cw(oldpaper) for |i(refer) citations
and converts them to |i(prefer) commands,
writing the output to |cw(newpaper).


|section(Acknowledgements)

Sharon Peeters and Ted Kowalski
encouraged me to write |i(prefer) and then integrated
it into |i(monk).
The idea of using the |i(awk) language to format references
came from Ravi Sethi.
Julia Hirschberg, Joe Kruskal, and Ted Kowalski
contributed style scripts.
Thanks to those who offered feature suggestions
bug reports, and
comments on versions of
this paper
including
Judy Friedman,
Julia Hirschberg,
Andrew Hume,
Ted Kowalski,
Joe Kruskal,
Doug McIlroy,
Mel Melchner,
Marcel Meth,
Sharon Murrel,
John Puttress,
Sande Pruzansky,
Ravi Sethi,
and
Wayne Wolf.


|environment(reference_placement;
|ifvalue sawreference on [
spacing on, blank.lines 3,
set string Ts "References",
inline off, size +1,
font bold, string Ts, font roman,
center off, size -1, inline on,
minimum.lines,
clear string Rs,
contents section 1 Rs Ts,
reference.placement
];
sawreference off)
|comment<summary: reference_placement (produce references here)>

|environment(appendix;
spacing on, blank.lines 3,
number format AC A, incr AC,
clear S0 S1 S2 S3,
set string Rs "Appendix ",
add string.from.number Rs AC,
divert.string Ts;
sectioning byappendix,
center on, size +1, font bold,
string Rs, blank.lines, string Ts,
font roman, size -1, center off,
minimum.lines 2, paragraph,
store string.from.number Rs AC,
contents section 1 Rs Ts)
|comment<summary: appendix (numbered appendix; IT)>
|reference_placement

|comment<|new_page>
|appendix(Bibliography Types And Attributes)
|save(types)

|insert(example/ptemplate.m)

.ne 3i
|appendix(Examples)
|save(examples)

This sample document contains many examples of
|cw<|sp(|s)reference> commands followed by
a |cw<|sp(|s)reference_placement>.

|begin(here)
|begin(figure)
|begin(small)
|insert(example/type.in)
|end(small)
|end(figure)
|end(here)

|p
When |i(prefer) formats this document according to |cw(acm) style
it looks like this:

|p
|begin(small)
|source(example/type.acm)
|end(small)

|p
When formatted according to |cw(apa) style
it looks like this:
|p
|begin(small)
|source(example/type.apa)
|end(small)