8.  Reference Files.

      A reference file is a set of bibliographic references usable with refer. It can be indexed using the software described in section 2 for fast searching. What refer does is to read the input document stream, looking for imprecise citation references. It then searches through reference files to find the full citations, and inserts them into the document. The format of the full citation is arranged to make it convenient for a macro package, such as the -ms macros, to format the reference for printing. Since the format of the final reference is determined by the desired style of output, which is determined by the macros used, refer avoids forcing any kind of reference appearance. All it does is define a set of string registers which contain the basic information about the reference; and provide a macro call which is expanded by the macro package to format the reference. It is the responsibility of the final macro package to see that the reference is actually printed; if no macros are used, and the output of refer fed untranslated to troff, nothing at all will be printed.

      The strings defined by refer are taken directly from the files of references, which are in the following format. The references should be separated by blank lines. Each reference is a sequence of lines beginning with % and followed by a key-letter. The remainder of that line, and successive lines until the next line beginning with %, contain the information specified by the key-letter. In general, refer does not interpret the information, but merely presents it to the macro package for final formatting. A user with a separate macro package, for example, can add new key-letters or use the existing ones for other purposes without bothering refer.

      The meaning of the key-letters given below, in particular, is that assigned by the -ms macros. Not all information, obviously, is used with each citation. For example, if a document is both an internal memorandum and a journal article, the macros ignore the memorandum version and cite only the journal article. Some kinds of information are not used at all in printing the reference; if a user does not like finding references by specifying title or author keywords, and prefers to add specific keywords to the citation, a field is available which is searched but not printed (K).

      The key letters currently recognized by refer and -ms, with the kind of information implied, are:

Key	    Information specified	     Key       Information specified
 A    Author's name			      N    Issue number
 B    Title of book containing item	      O    Other information
 C    City of publication		      P    Page(s) of article
 D    Date				      R    Technical report reference
 E    Editor of book containing item	      T    Title
 G    Government (NTIS) ordering number       V    Volume number
 I    Issuer (publisher)
 J    Journal name
 K    Keys (for searching)		      X    or
 L    Label				      Y    or
 M    Memorandum label			      Z    Information not used by refer
For example, a sample reference could be typed as:
%T Bounds on the Complexity of the Maximal
Common Subsequence Problem
%Z ctr127
%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ullman
%J J. ACM
%V 23
%N 1
%P 1-12
%M abcd-78
%D Jan. 1976
Order is irrelevant, except that authors are shown in the order given. The output of refer is a stream of string definitions, one for each of the fields of each reference, as shown below.
.]-
.ds [A authors' names ...
.ds [T title ...
.ds [J journal ...
...
.][ type-number
The refer program, in general, does not concern itself with the significance of the strings. The different fields are treated identically by refer, except that the X, Y and Z fields are ignored (see the -i option of mkey) in indexing and searching. All refer does is select the appropriate citation, based on the keys. The macro package must arrange the strings so as to produce an appropriately formatted citation. In this process, it uses the convention that the `T' field is the title, the `J' field the journal, and so forth.

      The refer program does arrange the citation to simplify the macro package's job, however. The special macro .]- precedes the string definitions and the special macro .][ follows. These are changed from the input .[ and .] so that running the same file through refer again is harmless. The .]- macro can be used by the macro package to initialize. The .][ macro, which should be used to print the reference, is given an argument type-number to indicate the kind of reference, as follows:

	     Value	   Kind of reference
	       1     Journal article
	       2     Book
	       3     Article within book
	       4     Technical report
	       5     Bell Labs technical memorandum
	       0     Other
The type is determined by the presence or absence of particular fields in the citation (a journal article must have a `J' field, a book must have an `I' field, and so forth). To a small extent, this violates the above rule that refer does not concern itself with the contents of the citation; however, the classification of the citation in troff macros would require a relatively expensive and obscure program. Any macro writer may, of course, preserve consistency by ignoring the argument to the .][ macro.

      The reference is flagged in the text with the sequence

\*([.number\*(.]
where number is the footnote number. The strings [. and .] should be used by the macro package to format the reference flag in the text. These strings can be replaced for a particular footnote, as described in section 5. The footnote number (or other signal) is available to the reference macro .][ as the string register [F. To simplify dealing with a text reference that occurs at the end of a sentence, refer treats a reference which follows a period in a special way. The period is removed, and the reference is preceded by a call for the string <. and followed by a call for the string >. For example, if a reference follows ``end.'' it will appear as
end\*(<.\*([.number\*(.]\*(>.
where number is the footnote number. The macro package should turn either the string >. or <. into a period and delete the other one. This permits the output to have either the form ``end[31].'' or ``end.31'' as the macro package wishes. Note that in one case the period precedes the number and in the other it follows the number.

      In some cases users wish to suspend the searching, and merely use the reference macro formatting. That is, the user doesn't want to provide a search key between .[ and .] brackets, but merely the reference lines for the appropriate document. Alternatively, the user can wish to add a few fields to those in the reference as in the standard file, or override some fields. Altering or replacing fields, or supplying whole references, is easily done by inserting lines beginning with %; any such line is taken as direct input to the reference processor rather than keys to be searched. Thus

.[
key1 key2 key3 ...
%Q New format item
%R Override report name
.]
makes the indicates changes to the result of searching for the keys. All of the search keys must be given before the first % line.

      If no search keys are provided, an entire citation can be provided in-line in the text. For example, if the eqn paper citation were to be inserted in this way, rather than by searching for it in the data base, the input would read

...
preprocessor like
.I eqn.
.[
%A B. W. Kernighan
%A L. L. Cherry
%T A System for Typesetting Mathematics
%J Comm. ACM
%V 18
%N 3
%P 151-157
%D March 1975
.]
It scans its input looking for items
...
This would produce a citation of the same appearance as that resulting from the file search.

      As shown, fields are normally turned into troff strings. Sometimes users would rather have them defined as macros, so that other troff commands can be placed into the data. When this is necessary, simply double the control character % in the data. Thus the input

.[
%V 23
%%M
Bell Laboratories,
Murray Hill, N.J. 07974
.]
is processed by refer into
.ds [V 23
.de [M
Bell Laboratories,
Murray Hill, N.J. 07974
..
The information after %%M is defined as a macro to be invoked by .[M while the information after %V is turned into a string to be invoked by \*([V. At present -ms expects all information as strings.