Utroff.org

Refer input and output format

Refer file

A reference file is a set of bibliographic references usable with refer. It can be indexed using the softwares inv and mkey for fast searching.

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 :

Refer output

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 : #-

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. 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 refer- ence 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 format- ting. 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
.[
%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
.]
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.

License

The text of this manual page comes from Some application of Inverted Indexes in the UNIX System by M. E. Lesk, which is distributed under the original BSD license.

See also

refer(1), sortbib(1), mkey(1), inv(1), hunt(1), and Some application of Inverted Indexes in the UNIX System by M. E. Lesk.

Help and bugs

Don’t hesitate to ask questions at help at utroff dot org. Please, send bugs and patches at help at utroff dot org.

Authors

M. E. Lesk. Modified by Pierre-Jean Fichet.