7.  Selecting and Formatting References for TROFF

      The major application of the retrieval software is refer, which is a troff preprocessor like eqn. kernighan cherry acm 1975 It scans its input looking for items of the form

.[
imprecise citation
.]
where an imprecise citation is merely a string of words found in the relevant bibliographic citation. This is translated into a properly formatted reference. If the imprecise citation does not correctly identify a single paper (either selecting no papers or too many) a message is given. The data base of citations searched may be tailored to each system, and individual users may specify their own citation files. On our system, the default data base is accumulated from the publication lists of the members of our organization, plus about half a dozen personal bibliographies that were collected. The present total is about 4300 citations, but this increases steadily. Even now, the data base covers a large fraction of local citations.

      For example, the reference for the eqn paper above was specified as

...
preprocessor like
.I eqn.
.[
kernighan cherry acm 1975
.]
It scans its input looking for items
...
This paper was itself printed using refer. The above input text was processed by refer as well as tbl and troff by the command
refer memo-file | tbl | troff -ms
and the reference was automatically translated into a correct citation to the ACM paper on mathematical typesetting.

      The procedure to use to place a reference in a paper using refer is as follows. First, use the lookbib command to check that the paper is in the data base and to find out what keys are necessary to retrieve it. This is done by typing lookbib and then typing some potential queries until a suitable query is found. For example, had one started to find the eqn paper shown above by presenting the query

$ lookbib
kernighan cherry
(EOT)
lookbib would have found several items; experimentation would quickly have shown that the query given above is adequate. Overspecifying the query is of course harmless; it is even desirable, since it decreases the risk that a document added to the publication data base in the future will be retrieved in addition to the intended document. The extra time taken by even a grossly overspecified query is quite small. A particularly careful reader may have noticed that ``acm'' does not appear in the printed citation; we have supplemented some of the data base items with extra keywords, such as common abbreviations for journals or other sources, to aid in searching.

      If the reference is in the data base, the query that retrieved it can be inserted in the text, between .[ and .] brackets. If it is not in the data base, it can be typed into a private file of references, using the format discussed in the next section, and then the -p option used to search this private file. Such a command might read (if the private references are called myfile)

refer -p myfile document | tbl | eqn | troff -ms . . .
where tbl and/or eqn could be omitted if not needed. The use of the -ms macros lesk typing documents unix gcos or some other macro package, however, is essential. Refer only generates the data for the references; exact formatting is done by some macro package, and if none is supplied the references will not be printed.

      By default, the references are numbered sequentially, and the -ms macros format references as footnotes at the bottom of the page. This memorandum is an example of that style. Other possibilities are discussed in section 5 below.