9.  Collecting References and other Refer Options

      Normally, the combination of refer and -ms formats output as troff footnotes which are consecutively numbered and placed at the bottom of the page. However, options exist to place the references at the end; to arrange references alphabetically by senior author; and to indicate references by strings in the text of the form [Name1975a] rather than by number. Whenever references are not placed at the bottom of a page identical references are coalesced.

      For example, the -e option to refer specifies that references are to be collected; in this case they are output whenever the sequence

.[
$LIST$
.]
is encountered. Thus, to place references at the end of a paper, the user would run refer with the -e option and place the above $LIST$ commands after the last line of the text. Refer will then move all the references to that point. To aid in formatting the collected references, refer writes the references preceded by the line
.]<
and followed by the line
.]>
to invoke special macros before and after the references.

      Another possible option to refer is the -s option to specify sorting of references. The default, of course, is to list references in the order presented. The -s option implies the -e option, and thus requires a

.[
$LIST$
.]
entry to call out the reference list. The -s option may be followed by a string of letters, numbers, and `+' signs indicating how the references are to be sorted. The sort is done using the fields whose key-letters are in the string as sorting keys; the numbers indicate how many of the fields are to be considered, with `+' taken as a large number. Thus the default is -sAD meaning ``Sort on senior author, then date.'' To sort on all authors and then title, specify -sA+T. And to sort on two authors and then the journal, write -sA2J.

      Other options to refer change the signal or label inserted in the text for each reference. Normally these are just sequential numbers, and their exact placement (within brackets, as superscripts, etc.) is determined by the macro package. The -l option replaces reference numbers by strings composed of the senior author's last name, the date, and a disambiguating letter. If a number follows the l as in -l3 only that many letters of the last name are used in the label string. To abbreviate the date as well the form -lm,n shortens the last name to the first m letters and the date to the last n digits. For example, the option -l3,2 would refer to the eqn paper (reference 3) by the signal Ker75a, since it is the first cited reference by Kernighan in 1975.

      A user wishing to specify particular labels for a private bibliography may use the -k option. Specifying -kx causes the field x to be used as a label. The default is L. If this field ends in -, that character is replaced by a sequence letter; otherwise the field is used exactly as given.

      If none of the refer-produced signals are desired, the -b option entirely suppresses automatic text signals.

      If the user wishes to override the -ms treatment of the reference signal (which is normally to enclose the number in brackets in nroff and make it a superscript in troff) this can be done easily. If the lines .[ or .] contain anything following these characters, the remainders of these lines are used to surround the reference signal, instead of the default. Thus, for example, to say ``See reference (2).'' and avoid ``See reference.2'' the input might appear

See reference
.[ (
imprecise citation ...
.]).
Note that blanks are significant in this construction. If a permanent change is desired in the style of reference signals, however, it is probably easier to redefine the strings [. and .] (which are used to bracket each signal) than to change each citation.

      Although normally refer limits itself to retrieving the data for the reference, and leaves to a macro package the job of arranging that data as required by the local format, there are two special options for rearrangements that can not be done by macro packages. The -c option puts fields into all upper case (CAPS-SMALL CAPS in troff output). The key-letters indicated what information is to be translated to upper case follow the c, so that -cAJ means that authors' names and journals are to be in caps. The -a option writes the names of authors last name first, that is A. D. Hall, Jr. is written as Hall, A. D. Jr. The citation form of the Journal of the ACM, for example, would require both -cA and -a options. This produces authors' names in the style KERNIGHAN, B. W. AND CHERRY, L. L. for the previous example. The -a option may be followed by a number to indicate how many author names should be reversed; -a1 (without any -c option) would produce Kernighan, B. W. and L. L. Cherry, for example.

      Finally, there is also the previously-mentioned -p option to let the user specify a private file of references to be searched before the public files. Note that refer does not insist on a previously made index for these files. If a file is named which contains reference data but is not indexed, it will be searched (more slowly) by refer using fgrep. In this way it is easy for users to keep small files of new references, which can later be added to the public data bases.