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