refer is a program for managing bibliographic references, and citing them in Roff documents. It is implemented as a preprocessor.
refer was written by Mike Lesk at Bell Laboratories[1][2] in or before 1978, and is now available as part of most Unix-like operating systems. A free reimplementation exists as part of the GNU Troff (groff) typesetting system. Another reimplementation named Neatrefer exists as part of the Neatroff project, although it lacks backwards compatibility with AT&T refer.[3]
As of 2015, refer sees little use, primarily because troff itself is not used much for longer technical writing that might need software support for reference and citation management. As of 2016, some reference management software (for instance, RefWorks) will import refer markup.
Example
refer works with a flat-file database of bibliographic records that includes works to which an author cites from their main document. Records contain line-delimited fields beginning with % and a character identifying the field-type, followed by a space, and then the field’s value, which consists of the rest of the line. Records are separated from each other by an empty line. For example, a refer database that contains two entries would look like this:
%A Brian W. Kernighan %A Lorinda L. Cherry %T A System for Typesetting Mathematics %J J. Comm. ACM %V 18 %N 3 %D March 1978 %P 151-157 %K eqn %A Donald Ervin Knuth %T Preliminary preliminary description of TEX %D 13 May 1977 %K texdraft
Citations are specified in Roff documents by listing keywords that uniquely match a reference:
.[
kernighan cherry eqn
.]
Putting this example in a realistic context, the following markup fragment, formatted with the command
$ REFER=/path/to/bibliography.db groff -R -ms <<DOC
EQN was designed to be understandable by laypeople,
.[
kernighan cherry eqn
.]
whereas TeX was designed for mathematicians and academics.
.[
knuth texdraft
.]
DOC
will generate output of the following form:
EQN was designed to be understandable by laypeople,1 whereas TeX was designed for mathematicians and academics.2
___________________
1 Brian W. Kernighan and Lorinda L. Cherry, “A System for Typesetting Mathematics,” J. Comm. ACM 18(3), pp. 151-157 (March 1978).
2 Donald Ervin Knuth, Preliminary preliminary description of TEX (13 May 1977).
Database fields
A refer bibliographic database is a text file consisting of a series of records, composed of line-delimited fields whose names (which must begin in the first column) are two-character codes that start with %-sign. The name is separated from the field’s value by exactly one space (U+0020). Empty fields are ignored. The conventional meaning of each field is shown in the table below. Compare this scheme with the newer EndNote scheme which uses a similar syntax.
For all fields except %A and %E, if there is more than one occurrence of a particular field in a record, only the last such field will be used.
| Field | Meaning |
|---|---|
| %A | The name of an author. If the name contains a title such as “Jr.” at the end, it should be separated from the last name by a comma. There can be multiple occurrences of the %A field. The order is significant. It is a good idea always to supply an %A field or a %Q field. |
| %B | For an article that is part of a book, the title of the book. |
| %C | The place (city) of publication. |
| %D | The date of publication. The year should be specified in full. If the month is specified, the name rather than the number of the month should be used, but only the first three letters are required. It is a good idea always to supply a %D field; if the date is unknown, a value such as “in press” or “unknown” should be used instead. |
| %E | For an article that is part of a book, the name of an editor of the book. Where the work has editors and no authors, the names of the editors should be given as %A fields and “, (ed)” or “, (eds)” should be appended to the last author. |
| %G | US Government ordering number. |
| %I | The publisher (issuer). |
| %J | For an article in a journal, the name of the journal. |
| %K | Keywords to be used for searching. |
| %L | Label. |
| %N | Journal issue number. |
| %O | Other information. This is usually printed at the end of the reference. |
| %P | Page number. A range of pages can be specified as “m–n“. |
| %Q | The name of the author, if the author is not a person. This will only be used if there are no %A fields. There can only be one %Q field. |
| %R | Technical report number. |
| %S | Series name. |
| %T | Title. For an article in a book or journal, this should be the title of the article. |
| %V | Volume number of the journal or book. |
| %X | Annotation. |
See also
Data schemes
- BibTeX § Database files – a text-based data format used by LaTeX
- EndNote § Tags and fields – a similar, but not identical, data scheme used by the EndNote program
- RIS – a text-based data scheme from Research Information Systems
Other
References
- ^ Lesk, Michael (1982). “Some applications of inverted indexes on the Unix system.”. UNIX Programmer’s Manual: Supplementary Documents. Vol. 2 (seventh ed.). Holt, Rinehart and Winston. Archived from the original on June 6, 2017.
- ^ McIlroy, M. D. (1987). A Research Unix reader: annotated excerpts from the Programmer’s Manual, 1971–1986 (PDF) (Technical report). CSTR. Bell Labs. 139.
- ^ Rudi, Ali Gholami (27 May 2022). “aligrudi/neatrefer: A refer preprocessor for neatroff”. GitHub. Retrieved 15 June 2026.
- ^ – Version 8 Unix Programmer’s Manual, dated c. February 1985.