refer

refer [ -a ] [ -b ] [ -c fields ] [ -e ] [ -i file ] [ -k keys ] [ -l num ] [ -n ] [ -o ] [ -p file ] [ -s keys ] [ -t ] [ -x ] [ -L ] [ -m macro ] [ file ... ]

-a
    Reverses the order of citations in the output.

-b
    Do not include references cited only by .[, .] if the input document does not contain explicit .[, .] lines.

-c fields
    Capitalizes the specified fields (e.g., T for title) in the references.

-e
    Sets global numbering for references across all files.

-i file
    Specifies an additional file to be searched for references. Can be used multiple times.

-k keys
    Sorts the output references based on the specified keys (e.g., AD for author-date).

-l num
    Uses et al. after num authors in the formatted reference.

-n
    Does not number the references in the bibliography.

-o
    Outputs a list of undefined references at the end of the run.

-p file
    Specifies a primary reference file to search. This file is searched before the default libraries.

-s keys
    Sorts the bibliography list by the specified keys.

-t
    Suppresses warning messages for unresolved references.

-x
    Suppresses warning messages for unknown items in reference files.

-L
    Searches standard system reference libraries for matching entries.

-m macro
    Specifies a macro package (e.g., ms, me) to be used for formatting.

The refer command is a preprocessor for roff document formatting systems like groff, troff, and nroff. It automates the inclusion and formatting of bibliographic citations and reference lists within a document. Users embed citations within their text using special macros (typically .[ and .]). refer reads these documents, searches designated bibliography files for the corresponding references, and then formats them according to specified styles or defaults. The output is a new document stream with formatted citations and a generated bibliography, which can then be piped to a roff formatter for final presentation. It's an essential tool for generating academic and technical papers in the roff ecosystem, handling tasks like numbering, sorting, and author-date formatting.

refer is tightly integrated with the roff suite and requires understanding of roff document structure and macro packages. Bibliography files must adhere to a specific flat-file database format with tagged fields (e.g., %A for author, %T for title). Its capabilities are less flexible than modern bibliographic management systems (like BibTeX or Zotero) and it is primarily used in environments where roff is the preferred text processing tool.

refer expects bibliography files to be plain text, with each reference entry separated by a blank line. Within each entry, fields are tagged with a percent sign (%) followed by a single uppercase letter, indicating the field type (e.g., %A for Author, %T for Title, %D for Date, %J for Journal, %K for Keywords).

Example entry:
%A John Doe
%T A Study on Linux Commands
%J Journal of Unix Studies
%V 10
%N 2
%D 2023
%K Linux, Command, Refer

Citations within the main document are typically enclosed by the roff macros .[ and .]. The content between these macros can be keywords or authors used to match entries in the bibliography files.

Example citation in document:
This concept was explored by Doe (.[John Doe, 2023]).
Another important work discusses this topic (.[A Study on Linux Commands]).

refer processes these to insert appropriate citations and build the bibliography list.

refer originated as part of the powerful troff text processing system developed at Bell Labs, alongside `nroff`, `eqn`, `tbl`, and `pic`. It was designed to manage and format bibliographic citations for academic and technical publications, a critical need in early Unix computing environments. Its development reflects the strong emphasis on document preparation in the Unix philosophy, providing robust tools for complex tasks before the advent of modern word processors. It remains a core component of the GNU roff (groff) suite, maintaining compatibility with its legacy.

groff(1), troff(1), nroff(1), addbib(1), lookbib(1), sortbib(1), indxbib(1)