# info > refer

---
type: CommandReference
command: refer
mode: man
section: "1"
source: man-pages
---

## Quick Reference

- `refer file` — process file with citations, output to stdout
- `refer -e file` — accumulate references, output at end
- `refer -b file` — suppress label in text and reference
- `refer -p database file` — specify bibliographic database
- `refer -s "A+ D." file` — sort references by author and date
- `refer -C file` — compatible mode (recognize .R1/.R2 even when followed by non-space)
- `refer --help` — display help
- `refer -v` — print version

## Name

refer — preprocess bibliographic references for groff

## Synopsis

refer [-benCPRS] [-a n] [-c fields] [-f n] [-i fields] [-k field]
      [-l m,n] [-p filename] [-s fields] [-t n] -B field.macro [file ...]
refer --help
refer -v
refer --version
## Options

Whitespace is permitted between an option and its argument.

*General options*
- `-v`, `--version` — Print version number
- `--help` — Display help
- `-R` — Do not recognize lines beginning with `.R1`/`.R2`
- `-C` — Compatible mode: recognize `.R1`/`.R2` even when followed by a character other than space or newline

*Citation processing*
- `-b` — Equivalent to `no-label-in-text` and `no-label-in-reference`
- `-e` — Equivalent to `accumulate`
- `-n` — Equivalent to `no-default-database`
- `-P` — Equivalent to `move-punctuation`
- `-S` — Equivalent to `label "(A.n|Q) ', ' (D.y|D)"` and `bracket-label " (" ) "; "`
- `-B` — Equivalent to `annotate X AP` and `no-label-in-reference`
- `-B field.macro` — Equivalent to `annotate field macro` and `no-label-in-reference`

*Formatting options*
- `-a n` — Equivalent to `reverse An` (reverse authors)
- `-c fields` — Equivalent to `capitalize fields`
- `-f n` — Equivalent to `label %n`
- `-k field` — Equivalent to `label field~%a`
- `-l` — Equivalent to `label A.nD.y%a`
- `-l m,n` — Equivalent to `label A.n+mD.y-n%a`
- `-s spec` — Equivalent to `sort spec`
- `-t n` — Equivalent to `search-truncate n`

*Database options*
- `-i fields` — Equivalent to `search-ignore fields`
- `-p filename` — Equivalent to `database filename` (and filenames on command line are processed as arguments to `bibliography`)

## Usage

### Bibliographic databases

Database records are separated by blank lines. Fields start with `%` at line beginning, followed by a one-character field name, exactly one space, then the field content. Empty fields are ignored.

**Standard fields:**
- `%A` — Author name (multiple allowed, order significant)
- `%B` — For an article in a book: book title
- `%C` — City of publication
- `%D` — Date (year in full; month name or first three letters)
- `%E` — Editor of book (for works with editors only, use `%A` with `, (ed)` or `, (eds)`)
- `%G` — US Government ordering number
- `%I` — Publisher
- `%J` — Journal name
- `%K` — Keywords for searching
- `%L` — Label
- `%N` — Journal issue number
- `%O` — Other information (printed at end of reference)
- `%P` — Page number(s); range as `m-n`
- `%Q` — Non-person author (used only if no `%A`)
- `%R` — Technical report number
- `%S` — Series name
- `%T` — Title (article title if in book/journal)
- `%V` — Volume number
- `%X` — Annotation

For fields other than `%A` and `%E`, only the last occurrence of a field is used. Accent strings should follow the character to be accented.

### Citations

Format:
.[opening-text
flags keywords
fields
.]closing-text
- `opening-text` and `closing-text` bracket the label (overrides `bracket-label` command).
- `flags` are non-alphanumeric characters modifying treatment:
  - `#` — Use short label (from `short-label` command)
  - `[` — Precede opening-text with first string from `bracket-label`
  - `]` — Follow closing-text with second string from `bracket-label`
- `keywords` — Words to search in bibliographic databases; must match exactly one reference.
- `fields` — Additional fields to replace or supplement those in the reference.

Labels are attached to the line preceding the `.[` line. Multiple citations with no intervening text have labels attached to the same line.

### Commands

Commands are placed between `.R1` and `.R2` lines. Each command is separated by newlines or `;`. `#` introduces a comment. Words can be quoted with `"`. Lines can be continued with `\`.

Most commands have a negative form `no-command` that undoes the effect.

**Important commands:**
- `abbreviate fields string1 string2 string3 string4` — Abbreviate first names in fields.
- `abbreviate-label-ranges string` — Merge consecutive labels (default `-`).
- `accumulate` — Accumulate references instead of outputting immediately.
- `annotate field string` — Mark field as annotation; printed at end of reference as paragraph preceded by `.string` (default field `X`, default string `AP`).
- `articles string...` — Definite/indefinite articles to ignore at beginning of `T` fields when sorting.
- `bibliography filename...` — Write out all references from listed databases.
- `bracket-label string1 string2 string3` — Wrap labels with `string1` and `string2`; adjacent `string2`+`string1` become `string3`.
- `capitalize fields` — Convert fields to caps and small caps.
- `compatible` — Recognize `.R1`/`.R2` even when followed by non-space.
- `database filename...` — Search listed databases (if index file `filename.i` exists, it is used instead).
- `date-as-label string` — Replace `D` field with `string` after label construction.
- `default-database` — Search default database (default on; `no-default-database` to disable).
- `discard fields` — Discard fields when reading reference (default `XYZ`).
- `et-al string m n` — Use `string` for truncated authors when number of unambiguous authors `u` and total `t` satisfy `t-u >= m` and `t >= n`.
- `include filename` — Include and interpret commands from `filename`.
- `join-authors string1 string2 string3` — Join authors: two authors with `string1`, more than two with `string2` then `string3`.
- `label-in-reference` — Define string `[F` as reference label (default on; `no-label-in-reference` to suppress).
- `label-in-text` — Output a label in the text (default on; `no-label-in-text` to suppress).
- `label string` — Label expression for each reference.
- `separate-label-second-parts string` — When merging two-part labels, separate second part with `string` (default `, `).
- `move-punctuation` — Move punctuation at end of line past the label.
- `reverse fields` — Reverse specified fields (each field name can be followed by a number; default all).
- `search-ignore fields` — Ignore fields when searching databases without index (default `XYZ`).
- `search-truncate n` — Only require first `n` characters of keys (default 6).
- `short-label string` — Alternative label expression for use with `#` flag.
- `sort string` — Sort references by field names (e.g., `A+ D.`); automatically accumulates.
- `sort-adjacent-labels` — Sort adjacent labels by reference list position.

### Label expressions

Label expressions are evaluated both normally (for output) and tentatively (for disambiguation). The following operators are available (highest precedence first):

- `field` or `field n` — The n-th part of field (default 1)
- `'string'` — Literal characters
- `@` — All authors joined as per `join-authors`; when sorted by author, uses last names and may truncate to avoid ambiguity (uses `et-al` string)
- `%n`, `%a`, `%A`, `%i`, `%I` — Serial number of reference (1 + number of earlier references with same tentative label)
- `expr*` — If another reference has same tentative label, output `expr`; else empty
- `expr+n`, `expr-n` — First (+) or last (-) n letters/digits of expr
- `expr.l` — Lowercase
- `expr.u` — Uppercase
- `expr.c` — Caps and small caps
- `expr.r` — Reverse (last name first)
- `expr.a` — Abbreviate first names
- `expr.y` — Year part
- `expr.+y` — Part before year
- `expr.-y` — Part after year
- `expr.n` — Last name part
- `expr1~expr2` — If last char of expr1 is `-`, replace with expr2
- `expr1 expr2` — Concatenation
- `expr1|expr2` — If expr1 non-empty, expr1 else expr2
- `expr1&expr2` — If expr1 non-empty, expr2 else empty
- `expr1?expr2:expr3` — If expr1 non-empty, expr2 else expr3
- `<expr>` — Two-part label; adjacent labels with same first part are merged with `separate-label-second-parts` string
- `(expr)` — Grouping

### Macro interface

Each reference invokes macro `]-` with string `[F` defined as the label (unless `no-label-in-reference`). Field strings are defined as `[X` for field `X`. Number register `[P` is set to 1 if page range. `[T`, `[A`, `[O` set to 1 if field ends with `.?!`. `[E` set to 1 if `[E` string contains multiple names. Reference ends with macro `][` with arguments: type number (1=journal article, 2=book, 3=article in book, 4=tech report, 0=other) and symbolic name. Groups of accumulated references are preceded by `]<` and followed by `]>`.

## Examples

**Simple citation with keywords:**
.[
author keyword
.])
**Citation with explicit fields:**
.[
%T My Title
%A Smith, John
%D 2023
.])
**Using commands to sort and accumulate:**
.R1
sort A+
accumulate
.R2
.
.[
some keyword
.])
.
.R1
bibliography /path/to/database
.R2
## See Also

[indxbib(1)](http://localhost/phpMan.php/man/indxbib/1/markdown), [lookbib(1)](http://localhost/phpMan.php/man/lookbib/1/markdown), [lkbib(1)](http://localhost/phpMan.php/man/lkbib/1/markdown), [groff(1)](http://localhost/phpMan.php/man/groff/1/markdown)