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