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