BSD 4_3 release

[unix-history] / usr / man / man1 / refer.1

diff --git a/usr/man/man1/refer.1 b/usr/man/man1/refer.1
index fae3d6e..d7c3a09 100644 (file)
--- a/usr/man/man1/refer.1
+++ b/usr/man/man1/refer.1
@@ -1,113 +1,265 @@
-.TH REFER 1 "8 February 1983"
+.\"    @(#)refer.1     6.2 (Berkeley) 5/12/86
+.\"
+.TH REFER 1 "May 12, 1986"
+.AT 3

 .SH NAME
 refer \- find and insert literature references in documents
 .SH SYNOPSIS
 .B refer
 .SH NAME
 refer \- find and insert literature references in documents
 .SH SYNOPSIS
 .B refer

-[ option ... ]
+[
+.B \-a
+] [
+.B \-b
+] [
+.B \-c
+] [
+.B \-e
+] [
+.BI \-f n
+] [
+.BI \-k x
+] [
+.BI \-l m,n
+] [
+.B \-n
+] [
+.B \-p
+bib
+] [
+.BI \-s keys
+] [
+.BI \-B l.m
+] [
+.B \-P
+] [
+.B \-S
+] [ file ... ]

 .SH DESCRIPTION
 .I Refer
 .SH DESCRIPTION
 .I Refer

-is a preprocessor for 
-.IR nroff (1),
+is a preprocessor for
+.I nroff

 or
 or

-.IR troff (1),
-that finds and formats references.  The input files (standard input by
-default) are copied to the standard output, except for lines between .[
-and .] command lines.  Such lines are assumed to contain keywords as for
-.IR lookbib (1),
-and are replaced by information from a bibliographic data base.  The
-user can avoid the search, override fields from it, or add new fields.
-The reference data, from whatever source, is assigned to a set of 
+.IR troff (1)
+that finds and formats references for footnotes or endnotes.
+It is also the base for a series of programs designed to
+index, search, sort, and print stand-alone bibliographies,
+or other data entered in the appropriate form.
+.PP
+Given an incomplete citation with sufficiently precise keywords,
+.I refer
+will search a bibliographic database for references
+containing these keywords anywhere in the title, author, journal, etc.
+The input file (or standard input)
+is copied to standard output,
+except for lines between .[ and .] delimiters,
+which are assumed to contain keywords,
+and are replaced by information from the bibliographic database.
+The user may also search different databases,
+override particular fields, or add new fields.
+The reference data, from whatever source, are assigned to a set of

 .I troff
 .I troff

-strings.  Macro packages such as 
+strings.
+Macro packages such as

 .IR ms (7)
 .IR ms (7)

-print the finished reference text from these strings.  A flag is placed
-in the text at the point of reference.  By default, the references are
-indicated by numbers.
-.LP
+print the finished reference text from these strings.
+By default references are flagged by footnote numbers.
+.PP

 The following options are available:
 The following options are available:

+.TP 6
+.BI \-a n
+Reverse the first
+.I n
+author names (Jones, J. A. instead of J. A. Jones).
+If
+.I n
+is omitted all author names are reversed.
+.ns

 .TP
 .TP

-.BI -a r
-Reverse the first 
-.I r
-author names (Jones, J. A. instead of J. A. Jones).  If 
-.I r
-is omitted, all author names are reversed.
-.TP
-.B -b
-Bare mode \(em do not put any flags in text (neither numbers or labels).
+.B \-b
+Bare mode: do not put any flags in text (neither numbers nor labels).
+.ns

 .TP
 .TP

-.BI -c string
-Capitalize (with C\s-2APS\s+2 S\s-2MALL\s+2 SC\s-2APS\s+2) the fields
-whose key-letters are in 
-.IR string .
+.BI \-c keys
+Capitalize (with C\s-2APS\s0 S\s-2MALL\s+2 C\s-2APS\s0)
+the fields whose key-letters are in
+.IR keys .
+.ns

 .TP
 .TP

-.B -e
-Instead of leaving the references where encountered, accumulate them
-until a sequence of the form:
+.B \-e
+Instead of leaving the references where encountered,
+accumulate them until a sequence of the form

 .nf
 .nf

-.in +1.0i
-\&.[
-$LIST$
-\&.]
+       .[
+       $LIST$
+       .]

 .fi
 .fi

-.in -1.0i

 is encountered, and then write out all references collected so far.
 is encountered, and then write out all references collected so far.

-Collapse references to the same source.
+Collapse references to same source.
+.ns
+.TP
+.BI \-f n
+Set the footnote number to
+.I n
+instead of the default of 1 (one).
+With labels rather than numbers,
+this flag is a no-op.
+.ns

 .TP
 .TP

-.BI -k x
-Instead of numbering references, use labels as specified in a reference
-data line beginning with the characters 
-.IR %x ;
-By default, 
+.BI \-k x
+Instead of numbering references, use labels as specified in a
+reference data line beginning
+.I %x;
+by default

 .I x
 is
 .I x
 is

-.BR L .
+.B L.
+.ns

 .TP
 .TP

-.RI -l m , n
-Instead of numbering references, use labels from the senior author's
-last name and the year of publication.  Only the first
+.BI \-l m , n
+Instead of numbering references, use labels made from
+the senior author's last name and the year of publication.
+Only the first
+.I m
+letters of the last name
+and the last
+.I n
+digits of the date are used.
+If either

 .I m
 .I m

-letters of the last name and the last 
+or

 .I n
 .I n

-digits of the date are used.  If either of 
-.IR m or ,n
-is omitted, the entire name or date respectively is used.
+is omitted the entire name or date respectively is used.
+.ns

 .TP
 .TP

-.B -p
-Take the next argument as a file of references to be searched.  The
-default file is searched last.
+.B \-n
+Do not search the default file /usr/dict/papers/Ind.
+If there is a REFER environment variable,
+the specified file will be searched instead of the default file;
+in this case the
+.B \-n
+flag has no effect.
+.ns

 .TP
 .TP

-.B -n
-Do not search the default file.
+.BI \-p \0bib
+Take the next argument
+.I bib
+as a file of references to be searched.
+The default file is searched last.
+.ns

 .TP
 .TP

-.BI -s keys
-Sort references by fields whose key-letters are in the 
+.BI \-s keys
+Sort references by fields whose key-letters are in the

 .I keys
 .I keys

-string, and permute reference numbers in the text accordingly.  Using
-this option implies the 
-.B -e
-option.  The key-letters in
+string;
+permute reference numbers in text accordingly.
+Implies
+.BR \-e .
+The key-letters in

 .I keys
 .I keys

-may be followed by a number indicating how many such fields are used,
-with a + sign taken as a very large number.  The default is 
-.BR AD ,
-which sorts on the senior author and date.  To sort on all authors and
-then the date, for instance, use the options 
+may be followed by a number to indicate how many such fields
+are used, with
+.B +
+taken as a very large number.
+The default is
+.B AD
+which sorts on the senior author and then date; to sort, for example,
+on all authors and then title, use

 .BR -sA+T .
 .BR -sA+T .

-.LP
+.ns
+.TP
+.BI \-B l.m
+Bibliography mode.
+Take a file composed of records separated by blank lines,
+and turn them into
+.I troff
+input.
+Label
+.I l
+will be turned into the macro
+.I .m
+with
+.I l
+defaulting to
+.B %X
+and
+.I .m
+defaulting to
+.B .AP
+(annotation paragraph).
+.ns
+.TP
+.B \-P
+Place punctuation marks .,:;?! after the reference signal,
+rather than before.
+(Periods and commas used to be done with strings.)
+.ns
+.TP
+.B \-S
+Produce references in the Natural or Social Science format.
+.PP
+To use your own references,
+put them in the format described below.
+They can be searched more rapidly by running
+.IR indxbib (1)
+on them before using
+.I refer;
+failure to index results in a linear search.

 When
 When

-.I Refer
-is used with
-.IR eqn (1),
-.IR neqn (1),
+.I refer
+is used with the
+.I eqn,
+.I neqn

 or
 or

-.IR tbl (1),
-.I Refer
-should be used fits in the sequence, to minimize the volume of data
-passed through pipes.
-.SH FILES
-.ta 2.0i
+.I tbl
+preprocessors
+.I refer
+should be first, to minimize the volume
+of data passed through pipes.
+.PP
+The
+.I refer
+preprocessor and associated programs
+expect input from a file of references
+composed of records separated by blank lines.
+A record is a set of lines (fields),
+each containing one kind of information.
+Fields start on a line beginning with a ``%'',
+followed by a key-letter, then a blank,
+and finally the contents of the field,
+and continue until the next line starting with ``%''.
+The output ordering and formatting of fields
+is controlled by the macros specified for
+.I nroff/troff
+(for footnotes and endnotes) or
+.I roffbib
+(for stand-alone bibliographies).
+For a list of the most common key-letters
+and their corresponding fields, see
+.IR addbib (1).
+An example of a
+.I refer
+entry is given below.
+.SH EXAMPLE
+.PP

 .nf
 .nf

-/usr/dict/papers       directory of default publication lists and indexes
-/usr/lib/refer directory of programs
+%A     M. E. Lesk
+%T     Some Applications of Inverted Indexes on the \s-1UNIX\s0 System
+%B     \s-1UNIX\s0 Programmer's Manual
+%V     2b
+%I     Bell Laboratories
+%C     Murray Hill, NJ
+%D     1978

 .fi
 .fi

+.SH FILES
+.ta \w'/usr/dict/papers\0\0'u
+/usr/dict/papers       directory of default publication lists
+.br
+/usr/lib/refer         directory of companion programs
+.SH SEE ALSO
+addbib(1), sortbib(1), roffbib(1), indxbib(1), lookbib(1)
+.SH AUTHOR
+Mike Lesk
+.SH BUGS
+Blank spaces at the end of lines in bibliography fields
+will cause the records to sort and reverse incorrectly.
+Sorting large numbers of references causes a core dump.