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 referFor example, a sample reference could be typed as:
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 OtherThe 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
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
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
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