Finds and inserts literature references in documents.
refer [ -b ] [ -e ] [ -P ] [ -S ] [ -a [ Number ] ] [ -B Label.Macro ] [ -c Keys ] [ -f Number | -k Label | -l Letter, Digit ] [ -n ] [ -p Reference ] [ -s Keys ] [ File ... ]
The refer command is a preprocessor for the nroff or the troff command. The refer command finds and formats references for footnotes or endnotes. It is also the basis for a series of programs designed to index, search, sort, and print standalone bibliographies or other data entered in the appropriate form.
Given an incomplete citation with sufficiently precise keywords, the refer command searches a bibliographic database for references containing these keywords anywhere in the title, author, journal, and so on. The input file (or else standard input) is copied to standard output, except for lines enclosed by the .[ (period, left bracket) and .] (period, right bracket) delimiters. Lines enclosed by the delimiters are assumed to contain keywords and are replaced by information from the bibliographic database. The user can search different databases, override particular fields, or add new fields. The reference data, from whatever source, is assigned to a set of troff command strings. Macro packages, such as the ms macro package, print the finished reference text from these strings. By default, references are flagged by footnote numbers.
To use your own references, put them in the format described in the Example section. These references can be accessed either by using the -p flag or by setting the REFER environment variable to those reference files. The references can be searched more rapidly by running the indxbib command on them before using the refer command. If you do not index, a linear search is made. When the refer command is used with any of the preprocessor commands (eqn, neqn, or tbl command), the refer command should be issued first, to minimize the volume of data passed through pipes.
Note: Anytime you edit a reference file, you must reissue the indxbib command on that file. If you do not use the indxbib command, remove any .ia, .ib, .ic, and .ig files associated with that reference file; otherwise, you will get a too many hits error message from the refer command.
The refer command and associated programs expect input from a file of references composed of records separated by blank lines. A record is a set of fields (lines), each containing one kind of information. Fields start on a line beginning with the % (percent sign), followed by a key letter, a space character, 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 the nroff and troff commands (for footnotes and endnotes), or the roffbib command (for standalone bibliographies). For a list of the most common key letters and their corresponding fields, see the addbib command.
| -b | Bare mode: do not put any flags in text (either numbers or labels). |
| -e | Instead of leaving the references where encountered, accumulates
them until a sequence of the following form is encountered:
.[ $LIST$ .] then writes out all references collected so far. |
| -P | Places punctuation marks after the reference signal, rather than before. The punctuation marks are locale-specific and are defined in the refer message catalog. |
| -S | Produces references in the natural or social science format. |
| -a Number | Reverses the first specified number of author names (Jones, J. A. instead of J. A. Jones). If the Number variable is omitted, all author names are reversed. |
| -B Label.Macro | Specifies bibliography mode. Takes a file composed of records separated by blank lines and turns that file into troff command input. The specified label is turned into the specified macro, with the Label variable value defaulting to %X and the .Macro variable value defaulting to .AP (annotation paragraph). |
| -c Keys | Capitalizes, with SMALL CAPS, the fields whose key letters are in the Keys variable. For example, Jack becomes JACK . |
| -f Number | Sets the footnote number to the specified number instead of the default of 1. With labels rather than numbers, this flag has no effect. See the -k flag and the -l flag. |
| -k Label | Instead of numbering references, uses labels as specified in a reference data line beginning with %Label. By default, the Label variable value is L. |
| -l Letter,Digit | Instead of numbering references, uses labels made from the senior author's last name and the year of publication. Only the first specified letters of the last name and the last specified digits of the date are used. If either the Letter variable or the Digit variable is omitted, the entire name or date, respectively, is used. |
| -n | Does not search the default /usr/share/dict/papers/Ind file .If the REFER environment variable is set, the specified file is searched instead of the default file. In this case, the -n flag has no effect. |
| -p Reference | Takes the Reference variable as a file of references to be searched. The default file is searched last. |
| -s Keys | Sorts references by fields whose key letters are specified by the Keys variable string. Renames reference numbers in text
accordingly. Implies the -e flag. The key letters specified
by the Keys variable can be followed by a number to
indicate how many such fields are used, with q + (plus sign) indicating a
very large number. The default value is AD, which sorts
first by senior author and then by date. For example, to sort on all authors
and then title, enter -sA+T.
It is important to note that blank spaces at the end of lines in bibliography fields cause the records to sort and reverse incorrectly. Sorting large numbers of references can cause a core dump. |
Following is an example of a refer command entry:
| /usr/share/dict/papers/Ind | Contains the default reference file. |
| /usr/lbin/refer | Contains companion programs. |
The eqn command, addbib command, indxbib command, lookbib command, neqn command, nroff command, roffbib command, sortbib command, tbl command, troff command.