Book HomeBook TitleSearch this book
PreviousNext

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.

KeyMeaning
%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.

-clist
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$
.]
-kc
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.

-skeylist
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 | ...

PreviousHomeNext
17.3. picBook IndexIV. Software Development
Library Navigation Links

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