BSD 4_4 release

[unix-history] / usr / src / old / refer / refer / refer.1

diff --git a/usr/src/old/refer/refer/refer.1 b/usr/src/old/refer/refer/refer.1
index 6096f6a..9b7a4b7 100644 (file)
--- a/usr/src/old/refer/refer/refer.1
+++ b/usr/src/old/refer/refer/refer.1
@@ -1,164 +1,273 @@
-.\"    @(#)refer.1     4.1 (Berkeley) %G%
+.\" Copyright (c) 1985 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.TH REFER 1 4/1/81
-.AT 3
-.SH NAME
-refer, lookbib \- find and insert literature references in documents
-.SH SYNOPSIS
-.B refer
-[ option ] ...
-.PP
-.B lookbib
-[ file ] ...
-.SH DESCRIPTION
-.I Lookbib
-accepts keywords from the standard input 
-and searches a bibliographic data base for references
-that contain those keywords anywhere in title, author,
-journal name, etc.
-Matching references are printed on the standard output.
-Blank lines are taken as delimiters between queries.
-.PP
-.I Refer
+.\" This module is believed to contain source code proprietary to AT&T.
+.\" Use and redistribution is subject to the Berkeley Software License
+.\" Agreement and your Software Agreement with AT&T (Western Electric).
+.\"
+.\"    @(#)refer.1     6.7 (Berkeley) 8/8/91
+.\"
+.Dd August 8, 1991
+.Dt REFER 1
+.Os ATT 7th
+.Sh NAME
+.Nm refer
+.Nd find and insert literature references in documents
+.Sh SYNOPSIS
+.Nm refer
+.Op Fl a
+.Op Fl b
+.Op Fl c
+.Op Fl e
+.Op Fl f Ns Ar n
+.Op Fl k Ns Ar x
+.Op Fl l Ns Ar m,n
+.Op Fl n
+.Op Fl p Ar bib
+.Op Fl s Ns Ar keys
+.Op Fl B Ns Ar l.m
+.Op Fl P
+.Op Fl S
+.Op Ar
+.Sh DESCRIPTION
+.Nm Refer

 is a preprocessor for
 is a preprocessor for

-.I nroff
+.Xr nroff 1

 or
 or

-.IR troff (1)
-that finds and formats references.
-The input files (standard input default) are copied to the standard output,
-except for lines between .[ and .]
-command lines, which are assumed to contain keywords as for
-.I lookbib,
-and are replaced by information from the bibliographic data base.
-The user may avoid the search, override fields from it, or
-add new fields.
+.Xr 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,
+.Nm 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
+.Ql \&.[
+and
+.Ql \&.]
+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
 The reference data, from whatever source, are assigned to a set of

-.I troff
+.Xr troff 1

 strings.
 Macro packages such as
 strings.
 Macro packages such as

-.IR ms (7)
+.Xr ms  7

 print the finished reference text from these strings.
 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.
-.br
-.sp
+By default references are flagged by footnote numbers.
+.Pp

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

-.TP 6
-.BI \-a r
+.Bl -tag -width flag
+.It Fl a Ns Ar n 

 Reverse the first
 Reverse the first

-.I r
+.Ar n

 author names (Jones, J. A. instead of J. A. Jones).
 If
 author names (Jones, J. A. instead of J. A. Jones).
 If

-.I r
+.Ar n

 is omitted all author names are reversed.
 is omitted all author names are reversed.

-.ns
-.TP
-.B \-b
+.It Fl b

 Bare mode: do not put any flags in text (neither numbers nor labels).
 Bare mode: do not put any flags in text (neither numbers nor labels).

-.ns
-.TP
-.BI \-c string
-Capitalize (with C\s-2APS\s0 S\s-2MALL\s+2 C\s-2APS\s0)
+.It Fl c Ns Ar keys 
+Capitalize (with C\s-2APS\s+2 S\s-2MALL\s+2 C\s-2APS\s+2)

 the fields whose key-letters are in
 the fields whose key-letters are in

-.IR string .
-.ns
-.TP
-.B \-e
+.Ar keys  .
+.It Fl e

 Instead of leaving the references where encountered,
 Instead of leaving the references where encountered,

-accumulate them
-until a sequence of the form
-.nf
-               .[
-               $LIST$
-               .]
-.fi
-is encountered, and then write out all references
-collected so far.  Collapse references to the same source.
-.ns
-.TP
-.BI \-k x
-Instead of numbering references, use labels as specified in
-a
-reference data line
-beginning
-.I %x;
-by default 
-.I x
+accumulate them until a sequence of the form
+.Bd -literal -offset indent -compact
+\&.[
+$LIST$
+\&.]
+.Ed
+is encountered, and then write out all references collected so far.
+Collapse references to same source.
+.It Fl f Ns Ar n 
+Set the footnote number to
+.Ar n
+instead of the default of 1 (one).
+With labels rather than numbers,
+this flag is a no-op.
+.It Fl k Ns Ar x 
+Instead of numbering references, use labels as specified in a
+reference data line beginning
+.Ar \&%x ;
+by default
+.Ar x

 is
 is

-.B L.
-.ns
-.TP
-.BI \-l m , n
+.Cm L .
+.It Fl l Ns Ar m,n 

 Instead of numbering references, use labels made from
 the senior author's last name and the year of publication.
 Only the first
 Instead of numbering references, use labels made from
 the senior author's last name and the year of publication.
 Only the first

-.I m
+.Ar m

 letters of the last name
 and the last
 letters of the last name
 and the last

-.I n
+.Ar n

 digits of the date are used.
 If either
 digits of the date are used.
 If either

-.I m
+.Ar m

 or
 or

-.BI , n
+.Ar n

 is omitted the entire name or date respectively is used.
 is omitted the entire name or date respectively is used.

-.ns
-.TP
-.B \-p
-Take the next argument as a file of
-references to be searched.
+.It Fl n
+Do not search the default file
+.Pa /var/db/Ind .
+If there is a
+.Ev REFER
+environment variable,
+the specified file will be searched instead of the default file;
+in this case the
+.Fl n
+flag has no effect.
+.It Fl p Ns Ar bib 
+Take the next argument
+.Ar bib
+as a file of references to be searched.

 The default file is searched last.
 The default file is searched last.

-.ns
-.TP
-.B \-n
-Do not search the default file.
-.ns
-.TP
-.BI \-s keys
-Sort references by fields whose key-letters are in
-the
-.I keys
+.It Fl s Ns Ar keys 
+Sort references by fields whose key-letters are in the
+.Ar keys

 string;
 string;

-permute
-reference numbers in text accordingly.
+permute reference numbers in text accordingly.

 Implies
 Implies

-.BR \-e .
+.Fl e  .

 The key-letters in
 The key-letters in

-.I keys
+.Ar keys

 may be followed by a number to indicate how many such fields
 are used, with
 may be followed by a number to indicate how many such fields
 are used, with

-.B +
+.Cm +

 taken as a very large number.
 The default is
 taken as a very large number.
 The default is

-.B AD
+.Cm AD

 which sorts on the senior author and then date; to sort, for example,
 which sorts on the senior author and then date; to sort, for example,

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

 When
 When

-.I refer
-is used with
-.I eqn,
-.I neqn
+.Nm refer
+is used with the
+.Xr eqn 1 ,
+.Xr neqn 1

 or
 or

-.I tbl,
-.I refer
+.Xr tbl 1
+preprocessors
+.Nm refer

 should be first, to minimize the volume
 should be first, to minimize the volume

-of data passed through
-pipes.
-.SH FILES
-.ta 1.5i
-/usr/dict/papers       directory of default publication lists and indexes
-.br
-/usr/lib/refer directory of programs
-.SH SEE ALSO
+of data passed through pipes.
+.Pp
+The
+.Nm 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
+.Ql % ,
+followed by a key-letter, then a blank,
+and finally the contents of the field,
+and continue until the next line starting with
+.Ql % .
+The output ordering and formatting of fields
+is controlled by the macros specified for
+.Xr nroff 1
+or
+.Xr troff 1
+(for footnotes and endnotes) or
+.Xr roffbib 1
+(for stand-alone bibliographies).
+For a list of the most common key-letters
+and their corresponding fields, see
+.Xr addbib  1  .
+An example of a
+.Nm refer
+entry is given below.
+.Sh ENVIRONMENT
+The following environment variable is used by
+.Nm refer
+if it exists.
+.Bl -tag -width Fl
+.It Ev REFER
+Specify an alternate default search file for publication lists.
+.El
+.Sh EXAMPLES
+.Bd -literal -offset indent
+%A     M. E. Lesk
+%T     Some Applications of Inverted Indexes on the UNIX System
+%B     UNIX Programmer's Manual
+%V     2b
+%I     Bell Laboratories
+%C     Murray Hill, NJ
+%D     1978
+.Ed
+.Sh FILES
+.Bl -tag -width /usr/share/dict/papers -compact
+.It Pa /usr/share/dict/papers
+Directory of default publication lists.
+.It Pa /var/db/Ind
+Default search file (for
+.Em hunt
+phase).
+.It Pa /usr/share/dict/eign
+Contains common words.
+.It Pa /usr/libexec
+Directory where companion programs reside.
+.El
+.Sh SEE ALSO
+.Xr addbib 1 ,
+.Xr sortbib 1 ,
+.Xr roffbib 1 ,
+.Xr indxbib 1 ,
+.Xr lookbib 1
+.Sh HISTORY
+The
+.Nm Refer
+command appeared in
+.At v7 .
+.Sh AUTHOR
+.An 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.