## 17.4. refer

Along with several associated commands, `refer` is a preprocessor for managing a database of bibliographic references. The database is kept in a separate file, and short references within a document are replaced by an expanded formal version.

The alphabetical command summary at the end of this section lists the usage and options for `refer` and the other commands that work with bibliographic databases.

`refer` is not supplied with SVR4, but it is a standard part of Solaris.

### 17.4.1. Bibliographic Entries

Bibliographic databases are text files, with each entry separated from the next by one or more blank lines. Within an entry, each field consists of a key letter (given as `%`letter) and associated value. Values may continue onto subsequent lines, ending at the next line that starts with a `%`. For example:

>     %T 5-by-5 Palindromic Word Squares
>     %A M.D. McIlroy
>     %J Word Ways
>     %V 9
>     %P 199-202
>     %D 1976

Except for `%A` (the author), fields should only be supplied once. Irrelevant or inapplicable fields should not be provided.

Key | Meaning
--- | ---
`%A` | Author's name
`%B` | Book containing article
`%C` | City (place where published)
`%D` | Date of publication
`%E` | Editor of book containing article
`%F` | Footnote number or label (supplied by `refer`)
`%G` | Government order number
`%H` | Header commentary, printed before reference
`%I` | Issuer (publisher)
`%J` | Journal containing article
`%K` | Keywords to use in locating reference
`%L` | Label field used by `refer -k`
`%M` | Bell Labs Memorandum
`%N` | Number within volume
`%O` | Other commentary, printed at end of reference
`%P` | Page number(s)
`%Q` | Corporate or Foreign Author (unreversed)
`%R` | Report, paper, or thesis (unpublished)
`%S` | Series title
`%T` | Title of article or book
`%V` | Volume number
`%X` | Abstract (used by `roffbib`, not `refer`)
`%Y`, `%Z` | Ignored by `refer`

### 17.4.2. General Coding Scheme

In a document, use of `refer` might look like this:

>     Palindromes are fun.
>     Very large ones can be used to impress your friends.
>     Palindromic word squares
>     .[
>     %A McIlroy
>     .]
>     are even more amazing,
>     and should be reserved for impressing your boss.
>     ...
>     .SH REFERENCES
>     .[
>     $LIST$
>     .]

The document shown here uses `refer`'s collection mode (`-e`), where all the references are printed at the end of the document, instead of at each place they are referenced.

### 17.4.3. Alphabetical Summary of Commands

addbib | `addbib` [`options`] database Interactively add bibliography records to database. #### Options `-a` Don't prompt for an abstract. `-p` `file` Use file as the prompting “skeleton.” Each line should be a prompt, a tab, and then the key letter to write.
indxbib | `indxbib` `files` Create an inverted index for `refer` bibliographic database files. These are then used by `lookbib` and `refer`. #### Generated files For each original file x, `indxbib` creates four new files.
x`.ia` | The entry file
x`.ib` | The posting file
x`.ic` | The tag file
x`.ig` | The reference file
lookbib | `lookbib` `database` Search a bibliographic database created by `indxbib`. `lookbib` prompts with a `>` sign for keywords and prints all records matching the keyword. If none are found, only another `>` prompt appears. While `lookbib` works without the inverted index files created by `indxbib`, such operation is slower. See also addbib and indxbib.
  > refer | `refer` [`options`] files Process files for bibliographic references. Input is passed through to the output unchanged, except for lines bracketed by `.[` and `.]`. Such lines are taken to be references to citations kept in a separate database. Based on the keywords provided between the brackets, `refer` generates `troff` `.ds` commands that define strings containing the relevant pieces of information. It then generates calls to macros that can format the references appropriately. The ms and me macro packages contain macro definitions for use with `refer`. The line right before the call to `.[` will have a suitable string appended to its end to indicate the use of a reference. Using the `-e` option, references can be gathered for placement at the end as a group. #### Options `-a`[`n`] Reverse the first n author names (i.e., last name first). With no n, all names are reversed. `-b` Bare mode. Do not add inline references to the text. `-c` `list` Capitalize, with SMALL CAPS, those fields whose letters are given in list. `-e` Collect references for output at the end. References to the same source are only printed once. The references are printed when these lines are encountered:
  >     .[
  >     $LIST$
  >     .]
> `-k` `c` Instead of numbered references, use labeled references, where the data supplied is from field `%`c in the database. The default is `%L`. `-l`[`m`[`,``n`]] Instead of numbered references, use labeled references, where the label is generated based on the senior (first) author's last name, and the year of publication. If supplied, m and n indicate how many letters from the author's last name and the last n digits of the year. Otherwise, the full name and year are used. `-n` Do not search the default file (found in `/usr/lib/refer/papers`). `-p` `refsfile` Use refsfile as a list of references. `-s` `keylist` Sort references based on the fields listed in keylist. This implies `-e`. Each letter may be followed by a number, indicating how many of that field is to be used. A `+` is equivalent to infinity. The default is `-sAD`, which sorts on the senior author and date. #### Example Sort on all authors, and then the date; use `mybib` for references.
>     refer -sA+D -p mybib thesis.ms | tbl | eqn | troff -ms - | lp
> roffbib | `roffbib` [``options``] [`files`] Print a bibliographic database. `roffbib` is a shell script that processes the named files (or standard input if no files) through `refer` and prints the results as a bibliography. By default, the bibliography is formatted using `nroff`, use the `-Q` option to use `troff` instead. `roffbib` accepts the following `nroff`/`troff` options and simply passes them to the formatter: `-e`, `-h`, `-m`, `-n`, `-o`, `-q`, `-r`, `-s`, and `-T`. See Chapter 12, for more details. #### Options `-H` `header` Set the “header” (title) to header. The default is `BIBLIOGRAPHY`. (This option is in the script, but is not documented.) `-Q` Use `troff` instead of `nroff`. The page offset is set to one inch. `-V` Typeset for Versatec printer/plotter. While documented in the manpage, this option is not in the script. `-x` Format abstracts or comments in the `%X` field of a bibliographic reference. Useful for annotated bibliographies. `refer` does not use the `%X` field. #### Example Sort a database and print it to a PostScript printer:
>     sortbib refs | roffbib -Q -x | /usr/lib/lp/postscript/dpost | lp
> sortbib | `sortbib` [``option``] `files` Sort one or more bibliographic databases. Typically used for printing with `roffbib`. Up to 16 databases may be sorted. Records may not exceed 4096 bytes in length. #### Option `-s` `keys` Sort on the given keys. The first four keys influence the sort; the rest are ignored. Letters in keys correspond to the key letters in bibliography entries. Append a `+` to a letter to sort completely by that key before moving to the next. #### Examples Sort by authors first, then by date:
>     sortbib -sA+D myrefs | ...
> Sort by author, title, and date:
>     sortbib -sATD myrefs | ...

Copyright © 2003 O'Reilly & Associates. All rights reserved.