Refer

Introduction

Description

References

• Nroff/Troff User's Guide by J. F. Ossanna. [I have not seen this]
• groff 1.09 (warning: 843k) The GNU implementation of troff, including refer. [This is a full implementation of troff and refer]
• The tib documentation. [tib uses a format similar to refer]

Software Support

• addbib to add references.
• sortbib to sort references.
• roffbib to print the entire file using troff or nroff.
• indxbib to make an inverted index of references.
• lookbib to search for references using the index.

Dana Jacobsen maintains a list of some refer tools.

bp fully supports Refer. The new version of BibDB fully supports Refer.

Examples

%A Jim Gettys
%A Phil Karlton
%A Scott McGregor
%T The X Window System, Version 11
%J Software Practice and Experience
%V 20
%N S2
%D 1990
%X A technical overview of the X11 functionality.  This is an
update of the X10 TOG paper by Scheifler & Gettys.

Common problems

• The number of fields originally defined was rather small, so people have made up alternatives for where to put their data.
• The format of the fields is often not followed.
  • Author names in the %A field field should be given in normal order ("First M. Last"), not reversed ("Last, First"). The EndNote program makes this error when exporting to refer format.
  • Corporate authors are often incorrectly found in the %A field, when they belong in the Corporate/Foreign author field, %Q.
  • Some people put multiple authors on a %A line. This is incorrect. There should be one %A entry per author.
  • The title of a book goes in the title (%T) field, not the book field (%B) which is used for the title of the container of an article.
• Formatting characters are strange. For the refer and troff program to work correctly, all accents must have two backslashes in all fields but the %X field, which only uses one. This is an oddity of the way the field data is passed into the various programs.
• Ties are used to keep names together. The tie is troff is "\0", so the name "Valery Giscard d'Estaing" is entered, it should be "Valery Giscard\0d'Estaing".
• The documentation advises people to put the editor in the author field if there is no explicit author, e.g. "%A Jim Jones, ed.". This can make refer documents hard to correctly parse in an automated fashion.
• Many files have fields given more than once. The solution seems to be just to append them to the last field of that type (except for author, which can have multiple occurrences).
• Many people who use the refer program just put together any mish-mash file that produces the results they want in the output, without any concern for what type of record they have made. If refer mangles it to the right combination of name-reversals, underlining, and information content, they're happy. This causes nightmares for conversion (automated or not!) to a format which wants more information.

Format Description

Standard tags

H

Header commentary which is printed before the reference.

A

Author's name. Authors should be listed in order, with the senior author first. Names are given in "First Last" format. If the name contains a suffix, it should be appended at the end with a comma, e.g. "Jim Jones, Jr.". For books with an editor but no author, the editor can go in the author field with a suffix of "ed", "eds", or something similar.

Q

Corporate author. Some sources also say to put foreign authors who have no clear last name in this field, but others claim the name here should be that of a non-person. Last time I checked, foreign authors were still people.

T

Title of the article or book.

S

Title of the series.

J

Journal containing the article.

B

Book containing article.

R

Report, paper, or thesis type.

V

Volume.

N

Number with volume.

E

Editor of book containing article.

P

Page number(s).

I

Issuer. This is the publisher.

C

City where published. This is the publishers address.

D

Date of publication. The year should be specified in full, and the month name rather than number should be used.

O

Other information which is printed after the reference.

K

Keywords used by refer to help locate the reference.

L

Label used to number references when the -k flag of refer is used.

X

Abstract. This is not normally printed in a reference.

Other tags

F

Caption

G

US Government ordering number

W

Where the item can be found (location)

Here are some other fields I've seen used:

$

Price

*

Copyright information

M

Mathematical Reviews number. The BIB format (almost exactly like refer) uses this for the month, and has only the year in the %D field.

Y

Table of Contents

Z

Pages in the entire document. Tib reserves this for special use.

l

Language used for document.

U

Annotation. Some people use this for a WWW URL field.

W

Location of conference.