1.\" Copyright (c) 1985 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.proprietary.roff% 5.\" 6.\" @(#)refer.1 6.7 (Berkeley) 08/08/91 7.\" 8.Dd 9.Dt REFER 1 10.Os ATT 7th 11.Sh NAME 12.Nm refer 13.Nd find and insert literature references in documents 14.Sh SYNOPSIS 15.Nm refer 16.Op Fl a 17.Op Fl b 18.Op Fl c 19.Op Fl e 20.Op Fl f Ns Ar n 21.Op Fl k Ns Ar x 22.Op Fl l Ns Ar m,n 23.Op Fl n 24.Op Fl p Ar bib 25.Op Fl s Ns Ar keys 26.Op Fl B Ns Ar l.m 27.Op Fl P 28.Op Fl S 29.Op Ar 30.Sh DESCRIPTION 31.Nm Refer 32is a preprocessor for 33.Xr nroff 1 34or 35.Xr troff 1 36that finds and formats references for footnotes or endnotes. 37It is also the base for a series of programs designed to 38index, search, sort, and print stand-alone bibliographies, 39or other data entered in the appropriate form. 40.Pp 41Given an incomplete citation with sufficiently precise keywords, 42.Nm refer 43will search a bibliographic database for references 44containing these keywords anywhere in the title, author, journal, etc. 45The input file (or standard input) 46is copied to standard output, 47except for lines between 48.Ql \&.[ 49and 50.Ql \&.] 51delimiters, 52which are assumed to contain keywords, 53and are replaced by information from the bibliographic database. 54The user may also search different databases, 55override particular fields, or add new fields. 56The reference data, from whatever source, are assigned to a set of 57.Xr troff 1 58strings. 59Macro packages such as 60.Xr ms 7 61print the finished reference text from these strings. 62By default references are flagged by footnote numbers. 63.Pp 64The following options are available: 65.Bl -tag -width flag 66.It Fl a Ns Ar n 67Reverse the first 68.Ar n 69author names (Jones, J. A. instead of J. A. Jones). 70If 71.Ar n 72is omitted all author names are reversed. 73.It Fl b 74Bare mode: do not put any flags in text (neither numbers nor labels). 75.It Fl c Ns Ar keys 76Capitalize (with C\s-2APS\s+2 S\s-2MALL\s+2 C\s-2APS\s+2) 77the fields whose key-letters are in 78.Ar keys . 79.It Fl e 80Instead of leaving the references where encountered, 81accumulate them until a sequence of the form 82.Bd -literal -offset indent -compact 83\&.[ 84$LIST$ 85\&.] 86.Ed 87is encountered, and then write out all references collected so far. 88Collapse references to same source. 89.It Fl f Ns Ar n 90Set the footnote number to 91.Ar n 92instead of the default of 1 (one). 93With labels rather than numbers, 94this flag is a no-op. 95.It Fl k Ns Ar x 96Instead of numbering references, use labels as specified in a 97reference data line beginning 98.Ar \&%x ; 99by default 100.Ar x 101is 102.Cm L . 103.It Fl l Ns Ar m,n 104Instead of numbering references, use labels made from 105the senior author's last name and the year of publication. 106Only the first 107.Ar m 108letters of the last name 109and the last 110.Ar n 111digits of the date are used. 112If either 113.Ar m 114or 115.Ar n 116is omitted the entire name or date respectively is used. 117.It Fl n 118Do not search the default file 119.Pa /var/db/Ind . 120If there is a 121.Ev REFER 122environment variable, 123the specified file will be searched instead of the default file; 124in this case the 125.Fl n 126flag has no effect. 127.It Fl p Ns Ar bib 128Take the next argument 129.Ar bib 130as a file of references to be searched. 131The default file is searched last. 132.It Fl s Ns Ar keys 133Sort references by fields whose key-letters are in the 134.Ar keys 135string; 136permute reference numbers in text accordingly. 137Implies 138.Fl e . 139The key-letters in 140.Ar keys 141may be followed by a number to indicate how many such fields 142are used, with 143.Cm + 144taken as a very large number. 145The default is 146.Cm AD 147which sorts on the senior author and then date; to sort, for example, 148on all authors and then title, use 149.Fl sA+T . 150.It Fl B Ns Ar l.m 151Bibliography mode. 152Take a file composed of records separated by blank lines, 153and turn them into 154.Xr troff 1 155input. 156Label 157.Ar \&l 158will be turned into the macro 159.Ar \&.m 160with 161.Ar \&l 162defaulting to 163.Cm \&%X 164and 165.Cm \&.m 166defaulting to 167.Cm \&.AP 168(annotation paragraph). 169.It Fl P 170Place punctuation marks 171.Ql ".,:;?!" after the reference signal, 172rather than before. 173(Periods and commas used to be done with strings.) 174.It Fl S 175Produce references in the Natural or Social Science format. 176.El 177.Pp 178To use your own references, 179put them in the format described below. 180They can be searched more rapidly by running 181.Xr indxbib 1 182on them before using 183.Nm refer ; 184failure to index results in a linear search. 185When 186.Nm refer 187is used with the 188.Xr eqn 1 , 189.Xr neqn 1 190or 191.Xr tbl 1 192preprocessors 193.Nm refer 194should be first, to minimize the volume 195of data passed through pipes. 196.Pp 197The 198.Nm refer 199preprocessor and associated programs 200expect input from a file of references 201composed of records separated by blank lines. 202A record is a set of lines (fields), 203each containing one kind of information. 204Fields start on a line beginning with a 205.Ql % , 206followed by a key-letter, then a blank, 207and finally the contents of the field, 208and continue until the next line starting with 209.Ql % . 210The output ordering and formatting of fields 211is controlled by the macros specified for 212.Xr nroff 1 213or 214.Xr troff 1 215(for footnotes and endnotes) or 216.Xr roffbib 1 217(for stand-alone bibliographies). 218For a list of the most common key-letters 219and their corresponding fields, see 220.Xr addbib 1 . 221An example of a 222.Nm refer 223entry is given below. 224.Sh ENVIRONMENT 225The following environment variable is used by 226.Nm refer 227if it exists. 228.Bl -tag -width Fl 229.It Ev REFER 230Specify an alternate default search file for publication lists. 231.El 232.Sh EXAMPLES 233.Bd -literal -offset indent 234%A M. E. Lesk 235%T Some Applications of Inverted Indexes on the UNIX System 236%B UNIX Programmer's Manual 237%V 2b 238%I Bell Laboratories 239%C Murray Hill, NJ 240%D 1978 241.Ed 242.Sh FILES 243.Bl -tag -width /usr/share/dict/papers -compact 244.It Pa /usr/share/dict/papers 245Directory of default publication lists. 246.It Pa /var/db/Ind 247Default search file (for 248.Em hunt 249phase). 250.It Pa /usr/share/dict/eign 251Contains common words. 252.It Pa /usr/libexec 253Directory where companion programs reside. 254.El 255.Sh SEE ALSO 256.Xr addbib 1 , 257.Xr sortbib 1 , 258.Xr roffbib 1 , 259.Xr indxbib 1 , 260.Xr lookbib 1 261.Sh HISTORY 262The 263.Nm Refer 264command appeared in 265.At v7 . 266.Sh AUTHOR 267.An Mike Lesk 268.Sh BUGS 269Blank spaces at the end of lines in bibliography fields 270will cause the records to sort and reverse incorrectly. 271Sorting large numbers of references causes a core dump. 272