REFER(1)
NAME
refer − find and insert literature references in documents
USAGE
refer [ −ar ] [ −b ] [ −ckeys ] [ −e ] [ −fn ] [ −kx ] [ −lm,n ] [ −n ] [ −pbib ]
[ −skeys ] [ −Bl.m ] [ −P ] [ −S ] [ file ... ]
DESCRIPTION
Refer, a preprocessor for nroff(1) or troff(1), finds and formats references for footnotes or endnotes. It is also the base for a series of programs designed to index, search, sort, and print stand-alone bibliographies, or other data entered in the appropriate form.
Given an incomplete citation with sufficiently precise keywords, refer searches a bibliographic database for references containing these keywords anywhere in the title, author, journal, etc. The input file (or standard input) is copied to standard output, except for lines between “.[” and “.]” delimiters. These delimiters are assumed to contain keywords, and are replaced by information from the bibliographic database. You may also search different databases, override particular fields, or add new fields. All reference data is assigned to a set of troff(1) strings. Macro packages such as ms(7) print the finished reference text from these strings. By default, references are flagged by footnote numbers.
References can be searched more rapidly by running indxbib(1) on them before using refer. Failure to index results in a linear search. When combined with the eqn(1), neqn(1) or tbl(1) preprocessors, refer should be used first, to minimize the volume of data passed through pipes.
The refer preprocessor and associated programs expect input from a file of references composed of records separated by blank lines. A record is a set of lines (fields), each containing one kind of information. Fields start on a line beginning with a percent sign (%), followed by a keyletter, then a blank, and finally the contents of the field, and continue until the next line starting with a percent sign. The output ordering and formatting of fields is controlled by the macros specified for nroff(1), troff(1) (for footnotes and endnotes), or roffbib(1) (for stand-alone bibliographies). For a list of the most common keyletters and their corresponding fields, see addbib(1).
OPTIONS
−ar Reverse the first n author names (Jones, J. A. instead of J. A. Jones). If n is omitted, reverse all author names.
−b Bare mode: do not put any flags in text (neither numbers nor labels).
−ckeys Capitalize (with SMALL CAPS) the fields whose keyletters are in keys.
−e Accumulate references until encountering a sequence of the following form:
.[
$LIST$
.]
Then, write out all references collected so far. Collapse references to the same source.
−fn Set the footnote number to n instead of the default of one. With labels rather than numbers, this flag is a no-op.
−kx Use labels as specified in a reference data line beginning %x. By default, x is L.
−lm,n Use labels made from the senior author’s last name and the year of publication. Only the first m letters of the last name and the last n digits of the date are used. If either m or n is omitted, use the entire name or date, respectively.
−n Do not search the default /usr/dict/papers/Ind file. If a REFER environment variable exists, search the specified file instead of the default file; in this case the −n option has no effect.
−p bib Take the next argument bib as a file of references to be searched. Search the default file last.
−skeys Sort references by fields whose keyletters are in the keys string. Permute reference numbers in text accordingly. This option implies the −e option. The keyletters in keys may be followed by a number to indicate how many such fields are used, with a plus sign (+) taken as a very large number. The default is AD, which sorts on the senior author and then the publication date. For example, to sort on all authors and then the publication title, use −sA+T.
−Bl.m Bibliography mode. Take a file composed of records separated by blank lines, and turn them into troff(1) input. Turn label l into the macro .m, with l defaulting to %X and .m defaulting to .AP (annotation paragraph).
−P Place the punctuation marks (.,:;?!) after the reference signal, rather than before.
−S Produce references in the natural science or social science format.
EXAMPLE
To use your own references, put them in the format described below.
%AM. E. Lesk
%TSome Applications of Inverted Indexes on the UNIX System
%BUNIX Programmer’s Manual
%V2b
%IBell Laboratories
%CMurray Hill, NJ
%D1978
CAUTIONS
Blank spaces at the end of lines in bibliography fields cause the records to sort and reverse incorrectly. Sorting large numbers of references causes a core dump.
FILES
/usr/dict/papersdirectory of default publication lists
/usr/lib/refer directory of companion programs