Commit | Line | Data |
---|---|---|
b0f148cf KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
95f51977 | 5 | .\" @(#)refer.bib 6.1 (Berkeley) 6/2/86 |
b0f148cf | 6 | .\" |
eac78bb3 KM |
7 | .EH 'USD:29-%''Refer \(em A Bibliography System' |
8 | .OH 'Refer \(em A Bibliography System''USD:29-%' | |
b0f148cf KM |
9 | .if t .nr PD .5v |
10 | .nr LL 6.5i | |
11 | .nr FL 6i | |
12 | . \" AP - abstract paragraph | |
13 | .de AP | |
14 | .sp \\n(PDu | |
15 | .ti +\\n(PIu | |
16 | .. | |
eac78bb3 | 17 | .\".RP |
b0f148cf KM |
18 | .TL |
19 | Refer \(em A Bibliography System | |
20 | .AU | |
21 | Bill Tuthill | |
22 | .AI | |
23 | Computing Services | |
24 | University of California | |
25 | Berkeley, CA 94720 | |
26 | .AB | |
27 | \fBRefer\fP is a bibliography system that supports data entry, | |
28 | indexing, retrieval, sorting, runoff, convenient citations, | |
29 | and footnote or endnote numbering. | |
30 | This document assumes you know how to use some Unix editor, | |
31 | and that you are familiar with the \fBnroff/troff\fP text formatters. | |
32 | .AP | |
33 | The \fBrefer\fP program is a preprocessor for \fBnroff/troff,\fP | |
34 | like \fBeqn\fP and \fBtbl,\fP | |
35 | except that it is used for literature citations, | |
36 | rather than for equations and tables. | |
37 | Given incomplete but sufficiently precise citations, | |
38 | \fBrefer\fP finds references in a bibliographic database. | |
39 | The complete references are formatted as footnotes, | |
40 | numbered, and placed either at the bottom of the page, | |
41 | or at the end of a chapter. | |
42 | .AP | |
43 | A number of ancillary programs make \fBrefer\fP easier to use. | |
44 | The \fBaddbib\fP program is for creating and extending | |
45 | the bibliographic database; | |
46 | \fBsortbib\fP sorts the bibliography by author and date, | |
47 | or other selected criteria; | |
48 | and \fBroffbib\fP runs off the entire database, | |
49 | formatting it not as footnotes, | |
50 | but as a bibliography or annotated bibliography. | |
51 | .AP | |
52 | Once a full bibliography has been created, | |
53 | access time can be improved by making an index | |
54 | to the references with \fBindxbib\fP. | |
55 | Then, the \fBlookbib\fP program can be used to quickly retrieve | |
56 | individual citations or groups of citations. | |
57 | Creating this inverted index will speed up \fBrefer,\fP | |
58 | and \fBlookbib\fP will allow you to verify that a citation | |
59 | is sufficiently precise to deliver just one reference. | |
60 | .AE | |
61 | .\"end cover | |
62 | .SH | |
63 | Introduction | |
64 | .XS | |
65 | Introduction | |
66 | .XE | |
67 | .PP | |
68 | Taken together, the \fBrefer\fP programs constitute | |
69 | a database system for use with variable-length information. | |
70 | To distinguish various types of bibliographic material, | |
71 | the system uses labels composed of upper case letters, | |
72 | preceded by a percent sign and followed by a space. | |
73 | For example, one document might be given this entry: | |
74 | .DS | |
75 | %A Joel Kies | |
76 | %T Document Formatting on Unix Using the -ms Macros | |
77 | %I Computing Services | |
78 | %C Berkeley | |
79 | %D 1980 | |
80 | .DE | |
81 | Each line is called a field, | |
82 | and lines grouped together are called a record; | |
83 | records are separated from each other by a blank line. | |
84 | Bibliographic information follows the labels, | |
85 | containing data to be used by the \fBrefer\fP system. | |
86 | The order of fields is not important, | |
87 | except that authors should be entered | |
88 | in the same order as they are listed on the document. | |
89 | Fields can be as long as necessary, | |
90 | and may even be continued on the following line(s). | |
91 | .PP | |
92 | The labels are meaningful to \fBnroff/troff\fP macros, | |
93 | and, with a few exceptions, | |
94 | the \fBrefer\fP program itself does not pay attention to them. | |
95 | This implies that you can change the label codes, | |
96 | if you also change the macros used by \fBnroff/troff\fP\|. | |
97 | The macro package takes care of details like proper ordering, | |
98 | underlining the book title or journal name, | |
99 | and quoting the article's title. | |
100 | Here are the labels used by \fBrefer,\fP | |
101 | with an indication of what they represent: | |
102 | .DS | |
103 | %H Header commentary, printed before reference | |
104 | %A Author's name | |
105 | %Q Corporate or foreign author (unreversed) | |
106 | %T Title of article or book | |
107 | %S Series title | |
108 | %J Journal containing article | |
109 | %B Book containing article | |
110 | %R Report, paper, or thesis (for unpublished material) | |
111 | %V Volume | |
112 | %N Number within volume | |
113 | %E Editor of book containing article | |
114 | %P Page number(s) | |
115 | %I Issuer (publisher) | |
116 | %C City where published | |
117 | %D Date of publication | |
118 | %O Other commentary, printed at end of reference | |
119 | %K Keywords used to locate reference | |
120 | %L Label used by \-k option of \fBrefer\fP | |
121 | %X Abstract (used by \fBroffbib,\fP not by \fBrefer\fP) | |
122 | .DE | |
123 | Only relevant fields should be supplied. | |
124 | Except for %A, each field should be given only once; | |
125 | in the case of multiple authors, | |
126 | the senior author should come first. | |
127 | The %Q is for organizational authors, | |
128 | or authors with Japanese or Arabic names, | |
129 | in which cases the order of names should be preserved. | |
130 | Books should be labeled with the %T, not with the %B, | |
131 | which is reserved for books containing articles. | |
132 | The %J and %B fields should never appear together, | |
133 | although if they do, the %J will override the %B. | |
134 | If there is no author, just an editor, | |
135 | it is best to type the editor in the %A field, | |
136 | as in this example: | |
137 | .DS | |
138 | %A Bertrand Bronson, ed. | |
139 | .DE | |
140 | The %E field is used for the editor of a book (%B) | |
141 | containing an article, which has its own author. | |
142 | For unpublished material such as theses, use the %R field; | |
143 | the title in the %T field will be quoted, | |
144 | but the contents of the %R field will not be underlined. | |
145 | Unlike other fields, %H, %O, and %X should contain their own punctuation. | |
146 | Here is a modest example: | |
147 | .DS | |
148 | %A Mike E. Lesk | |
149 | %T Some Applications of Inverted Indexes on the Unix System | |
150 | %B Unix Programmer's Manual | |
151 | %I Bell Laboratories | |
152 | %C Murray Hill, NJ | |
153 | %D 1978 | |
154 | %V 2a | |
155 | %K refer mkey inv hunt | |
156 | %X Difficult to read paper that dwells on indexing strategies, | |
157 | giving little practical advice about using \efBrefer\efP. | |
158 | .DE | |
159 | Note that the author's name is given in normal order, | |
160 | without inverting the surname; | |
161 | inversion is done automatically, | |
162 | except when %Q is used instead of %A. | |
163 | We use %X rather than %O for the commentary | |
164 | because we do not want the comment printed all the time. | |
165 | The %O and %H fields are printed by both \fBrefer\fP and \fBroffbib;\fP | |
166 | the %X field is printed only by \fBroffbib,\fP | |
167 | as a detached annotation paragraph. | |
168 | .SH | |
169 | Data Entry with Addbib | |
170 | .XS | |
171 | Data Entry with Addbib | |
172 | .XE | |
173 | .PP | |
174 | The \fBaddbib\fP program is for creating | |
175 | and extending bibliographic databases. | |
176 | You must give it the filename of your bibliography: | |
177 | .DS | |
178 | % \fBaddbib database\fP | |
179 | .DE | |
180 | Every time you enter \fBaddbib\fP, it asks if you want instructions. | |
181 | To get them, type \fBy\fP\|; to skip them, type \s-2RETURN\s0. | |
182 | \fBAddbib\fP prompts for various fields, reads from the keyboard, | |
183 | and writes records containing the \fBrefer\fP codes to the database. | |
184 | After finishing a field entry, | |
185 | you should end it by typing \s-2RETURN\s0. | |
186 | If a field is too long to fit on a line, | |
187 | type a backslash (\e) at the end of the line, | |
188 | and you will be able to continue on the following line. | |
189 | Note: the backslash works in this capacity only inside \fBaddbib\fP. | |
190 | .PP | |
191 | A field will not be written to the database | |
192 | if nothing is entered into it. | |
193 | Typing a minus sign as the first character of any field | |
194 | will cause \fBaddbib\fP to back up one field at a time. | |
195 | Backing up is the best way to add multiple authors, | |
196 | and it really helps if you forget to add something important. | |
197 | Fields not contained in the prompting skeleton may be entered | |
198 | by typing a backslash as the last character before \s-2RETURN\s0. | |
199 | The following line will be sent verbatim to the database | |
200 | and \fBaddbib\fP will resume with the next field. | |
201 | This is identical to the procedure for dealing with long fields, | |
202 | but with new fields, don't forget the % key-letter. | |
203 | .PP | |
204 | Finally, you will be asked for an abstract (or annotation), | |
205 | which will be preserved as the %X field. | |
206 | Type in as many lines as you need, and end with a control-D | |
207 | (hold down the \s-2CTRL\s0 button, then press the \*Qd\*U key). | |
208 | This prompting for an abstract can be suppressed | |
209 | with the \fB\-a\fP command line option. | |
210 | .PP | |
211 | After one bibliographic record has been completed, | |
212 | \fBaddbib\fP will ask if you want to continue. | |
213 | If you do, type \s-2RETURN\s0\|; | |
214 | to quit, type \fBq\fP or \fBn\fP (quit or no). | |
215 | It is also possible to use one of the system editors | |
216 | to correct mistakes made while entering data. | |
217 | After the \*QContinue?\*U prompt, type any of the following: | |
218 | \fBedit, ex, vi,\fP or \fBed\fP \*- | |
219 | you will be placed inside the corresponding editor, | |
220 | and returned to \fBaddbib\fP afterwards, | |
221 | from where you can either quit or add more data. | |
222 | .PP | |
223 | If the prompts normally supplied by \fBaddbib\fP are not enough, | |
224 | are in the wrong order, or are too numerous, | |
225 | you can redefine the skeleton by constructing a promptfile. | |
226 | Create some file, to be named after the \-p command line option. | |
227 | Place the prompts you want on the left side, | |
228 | followed by a single \s-2TAB\s0 (control-I), then the \fBrefer\fP code | |
229 | that is to appear in the bibliographic database. | |
230 | \fBAddbib\fP will send the left side to the screen, | |
231 | and the right side, along with data entered, to the database. | |
232 | .SH | |
233 | Printing the Bibliography | |
234 | .XS | |
235 | Printing the Bibliography | |
236 | .XE | |
237 | .PP | |
238 | \fBSortbib\fP is for sorting the bibliography | |
239 | by author (%A) and date (%D), or by data in other fields. | |
240 | It is quite useful for producing bibliographies | |
241 | and annotated bibliographies, | |
242 | which are seldom entered in strict alphabetical order. | |
243 | It takes as arguments the names of up to 16 bibliography files, | |
244 | and sends the sorted records to standard output (the terminal screen), | |
245 | which may be redirected through a pipe or into a file. | |
246 | .PP | |
247 | The \-s\fIKEYS\fP\| flag to \fBsortbib\fP will sort by fields | |
248 | whose key-letters are in the \fIKEYS\fP\| string, | |
249 | rather than merely by author and date. | |
250 | Key-letters in \fIKEYS\fP\| may be followed by a `+' | |
251 | to indicate that all such fields are to be used. | |
252 | The default is to sort by senior author and date | |
253 | (printing the senior author last name first), | |
254 | but \-sA+D will sort by all authors and then date, | |
255 | and \-sATD will sort on senior author, then title, and then date. | |
256 | .PP | |
257 | \fBRoffbib\fP is for running off the (probably sorted) bibliography. | |
258 | It can handle annotated bibliographies \*- | |
259 | annotations are entered in the %X (abstract) field. | |
260 | \fBRoffbib\fP is a shell script that calls | |
261 | \fBrefer\0\-B\fP and \fBnroff\0\-mbib\fP\|. | |
262 | It uses the macro definitions that reside in /usr/lib/tmac/tmac.bib, | |
263 | which you can redefine if you know \fBnroff\fP and \fBtroff\fP. | |
264 | Note that \fBrefer\fP will print the %H and %O commentaries, | |
265 | but will ignore abstracts in the %X field; | |
266 | \fBroffbib\fP will print both fields, | |
267 | unless annotations are suppressed with the \-x option. | |
268 | .PP | |
269 | The following command sequence will lineprint the entire bibliography, | |
270 | organized alphabetically by author and date: | |
271 | .DS | |
272 | % \fBsortbib database | roffbib | lpr\fP | |
273 | .DE | |
274 | This is a good way to proofread the bibliography, | |
275 | or to produce a stand-alone bibliography at the end of a paper. | |
276 | Incidentally, \fBroffbib\fP accepts all flags used with \fBnroff\fP. | |
277 | For example: | |
278 | .DS | |
279 | % \fBsortbib database | roffbib \-Tdtc \-s1\fP | |
280 | .DE | |
281 | will make accent marks work on a DTC daisy-wheel printer, | |
282 | and stop at the bottom of every page for changing paper. | |
283 | The \-n and \-o flags may also be quite useful, | |
284 | to start page numbering at a selected point, | |
285 | or to produce only specific pages. | |
286 | .PP | |
287 | \fBRoffbib\fP understands four command-line number registers, | |
288 | which are something like the two-letter number registers in \-ms. | |
289 | The \-rN1 argument will number references beginning at one (1); | |
290 | use another number to start somewhere besides one. | |
291 | The \-rV2 flag will double-space the entire bibliography, | |
292 | while \-rV1 will double-space the references, | |
293 | but single-space the annotation paragraphs. | |
294 | Finally, specifying \-rL6i changes the line length | |
295 | from 6.5 inches to 6 inches, | |
296 | and saying \-rO1i sets the page offset | |
297 | to one inch, instead of zero. | |
298 | (That's a capital O after \-r, not a zero.) | |
299 | .SH | |
300 | Citing Papers with Refer | |
301 | .XS | |
302 | Citing Papers with Refer | |
303 | .XE | |
304 | .PP | |
305 | The \fBrefer\fP program normally copies input to output, | |
306 | except when it encounters an item of the form: | |
307 | .DS | |
308 | \&.[ | |
309 | partial citation | |
310 | \&.] | |
311 | .DE | |
312 | The partial citation may be just an author's name and a date, | |
313 | or perhaps a title and a keyword, or maybe just a document number. | |
314 | \fBRefer\fP looks up the citation in the bibliographic database, | |
315 | and transforms it into a full, properly formatted reference. | |
316 | If the partial citation does not correctly identify a single work | |
317 | (either finding nothing, or more than one reference), | |
318 | a diagnostic message is given. | |
319 | If nothing is found, it will say \*QNo such paper.\*U | |
320 | If more than one reference is found, | |
321 | it will say \*QToo many hits.\*U | |
322 | Other diagnostic messages can be quite cryptic; | |
323 | if you are in doubt, use \fBchecknr\fP to verify | |
324 | that all your .['s have matching .]'s. | |
325 | .PP | |
326 | When everything goes well, | |
327 | the reference will be brought in from the database, | |
328 | numbered, and placed at the bottom of the page. | |
329 | This citation, | |
330 | .[ | |
331 | lesk inverted indexes | |
332 | .] | |
333 | for example, was produced by: | |
334 | .DS | |
335 | This citation, | |
336 | \&.[ | |
337 | lesk inverted indexes | |
338 | \&.] | |
339 | for example, was produced by | |
340 | .DE | |
341 | The .[ and .] markers, in essence, | |
342 | replace the .FS and .FE of the \-ms macros, | |
343 | and also provide a numbering mechanism. | |
344 | Footnote numbers will be bracketed on the the lineprinter, | |
345 | but superscripted on daisy-wheel terminals and in \fBtroff\fP\|. | |
346 | In the reference itself, articles will be quoted, | |
347 | and books and journals will be underlined in \fBnroff,\fP | |
348 | and italicized in \fBtroff.\fP | |
349 | .PP | |
350 | Sometimes you need to cite a specific page number | |
351 | along with more general bibliographic material. | |
352 | You may have, for instance, | |
353 | a single document that you refer to several times, | |
354 | each time giving a different page citation. | |
355 | This is how you could get \*Qp.\010\*U in the reference: | |
356 | .DS | |
357 | \&.[ | |
358 | kies document formatting | |
359 | %P 10 | |
360 | \&.] | |
361 | .DE | |
362 | The first line, a partial citation, | |
363 | will find the reference in your bibliography. | |
364 | The second line will insert the page number into the final citation. | |
365 | Ranges of pages may be specified as \*Q%P\056-78\*U. | |
366 | .PP | |
367 | When the time comes to run off a paper, | |
368 | you will need to have two files: | |
369 | the bibliographic database, and the paper to format. | |
370 | Use a command line something like one of these: | |
371 | .DS | |
372 | % \fBrefer \-p database paper | nroff \-ms\fP | |
373 | % \fBrefer \-p database paper | tbl | nroff \-ms\fP | |
374 | % \fBrefer \-p database paper | tbl | neqn | nroff \-ms\fP | |
375 | .DE | |
376 | If other preprocessors are used, | |
377 | \fBrefer\fP should precede \fBtbl,\fP | |
378 | which must in turn precede \fBeqn\fP or \fBneqn\fP\|. | |
379 | The \-p option specifies a \*Qprivate\*U database, | |
380 | which most bibliographies are. | |
381 | .SH | |
382 | Refer's Command-line Options | |
383 | .XS | |
384 | Refer's Command-line Options | |
385 | .XE | |
386 | .PP | |
387 | Many people like to place references at the end of a chapter, | |
388 | rather than at the bottom of the page. | |
389 | The \-e option will accumulate references | |
390 | until a macro sequence of the form | |
391 | .DS | |
392 | \&.[ | |
393 | $LIST$ | |
394 | \&.] | |
395 | .DE | |
396 | is encountered (or until the end of file). | |
397 | \fBRefer\fP will then write out all references collected | |
398 | up to that point, collapsing identical references. | |
399 | Warning: there is a limit (currently 200) | |
400 | on the number of references that can be accumulated at one time. | |
401 | .PP | |
402 | It is also possible to sort references that appear at the end of text. | |
403 | The \-s\fIKEYS\fP flag will sort references by fields | |
404 | whose key-letters are in the \fIKEYS\fP string, | |
405 | and permute reference numbers in the text accordingly. | |
406 | It is unnecessary to use \-e with it, since \-s implies \-e. | |
407 | Key-letters in \fIKEYS\fP may be followed by a `+' | |
408 | to indicate that all such fields are to be used. | |
409 | The default is to sort by senior author and date, | |
410 | but \-sA+D will sort on all authors and then date, | |
411 | and \-sA+T will sort by authors and then title. | |
412 | .PP | |
413 | \fBRefer\fP can also make citations in what is known as | |
414 | the Social or Natural Sciences format. | |
415 | Instead of numbering references, the \-l (letter ell) flag makes labels | |
416 | from the senior author's last name and the year of publication. | |
417 | For example, a reference to the paper on Inverted Indexes | |
418 | cited above might appear as [Lesk1978a]. | |
419 | It is possible to control the number of characters in the last name, | |
420 | and the number of digits in the date. | |
421 | For instance, the command line argument \-l6,2 might | |
422 | produce a reference such as [Kernig78c]. | |
423 | .PP | |
424 | Some bibliography standards shun both footnote numbers | |
425 | and labels composed of author and date, | |
426 | requiring some keyword to identify the reference. | |
427 | The \-k flag indicates that, instead of numbering references, | |
428 | key labels specified on the %L line should be used to mark references. | |
429 | .PP | |
430 | The \-n flag means to not search the default reference file, | |
431 | located in /usr/dict/papers/Rv7man. | |
432 | Using this flag may make \fBrefer\fP marginally faster. | |
433 | The \-a\fIn\fP flag will reverse the first \fIn\fP author names, | |
434 | printing Jones, J. A. instead of J. A. Jones. | |
435 | Often \-a1 is enough; this will reverse the names of only the senior author. | |
436 | In some versions of \fBrefer\fP there is also the \-f flag | |
437 | to set the footnote number to some predetermined value; | |
438 | for example, \-f23 would start numbering with footnote 23. | |
439 | .SH | |
440 | Making an Index | |
441 | .XS | |
442 | Making an Index | |
443 | .XE | |
444 | .PP | |
445 | Once your database is large and relatively stable, | |
446 | it is a good idea to make an index to it, | |
447 | so that references can be found quickly and efficiently. | |
448 | The \fBindxbib\fP program makes an inverted index | |
449 | to the bibliographic database | |
450 | (this program is called \fBpubindex\fP in the Bell Labs manual). | |
451 | An inverted index could be compared to | |
452 | the thumb cuts of a dictionary \*- | |
453 | instead of going all the way through your bibliography, | |
454 | programs can move to the exact location where a citation is found. | |
455 | .PP | |
456 | \fBIndxbib\fP itself takes a while to run, | |
457 | and you will need sufficient disk space to store the indexes. | |
458 | But once it has been run, access time will improve dramatically. | |
459 | Furthermore, large databases of several million characters | |
460 | can be indexed with no problem. | |
461 | The program is exceedingly simple to use: | |
462 | .DS | |
463 | % \fBindxbib database\fP | |
464 | .DE | |
465 | Be aware that changing your database will require | |
466 | that you run \fBindxbib\fP over again. | |
467 | If you don't, you may fail to find a reference | |
468 | that really is in the database. | |
469 | .PP | |
470 | Once you have built an inverted index, | |
471 | you can use \fBlookbib\fP to find references in the database. | |
472 | \fBLookbib\fP cannot be used until you have run \fBindxbib\fP\|. | |
473 | When editing a paper, \fBlookbib\fP is very useful | |
474 | to make sure that a citation can be found as specified. | |
475 | It takes one argument, the name of the bibliography, | |
476 | and then reads partial citations from the terminal, | |
477 | returning references that match, or nothing if none match. | |
478 | Its prompt is the greater-than sign. | |
479 | .DS | |
480 | % \fBlookbib database\fP | |
481 | > \fBlesk inverted indexes\fP | |
482 | %A Mike E. Lesk | |
483 | %T Some Applications of Inverted Indexes on the Unix System | |
484 | %J Unix Programmer's Manual | |
485 | %I Bell Laboratories | |
486 | %C Murray Hill, NJ | |
487 | %D 1978 | |
488 | %V 2a | |
489 | %X Difficult to read paper that dwells on indexing strategies, | |
490 | giving little practical advice about using \efBrefer\efP. | |
491 | > | |
492 | .DE | |
493 | If more than one reference comes back, | |
494 | you will have to give a more precise citation for \fBrefer\fP\|. | |
495 | Experiment until you find something that works; | |
496 | remember that it is harmless to overspecify. | |
497 | To get out of the \fBlookbib\fP program, | |
498 | type a control-D alone on a line; | |
499 | \fBlookbib\fP then exits with an ``EOT'' message. | |
500 | .PP | |
501 | \fBLookbib\fP can also be used to extract groups of related citations. | |
502 | For example, to find all the papers by Brian Kernighan | |
503 | found in the system database, and send the output to a file, type: | |
504 | .DS | |
505 | % \fBlookbib /usr/dict/papers/Ind > kern.refs\fP | |
506 | > \fBkernighan\fP | |
507 | > EOT | |
508 | % \fBcat kern.refs\fP | |
509 | .DE | |
510 | Your file, \*Qkern.refs\*U, will be full of references. | |
511 | A similar procedure can be used | |
512 | to pull out all papers of some date, | |
513 | all papers from a given journal, | |
514 | all papers containing a certain group of keywords, etc. | |
515 | .SH | |
516 | Refer Bugs and Some Solutions | |
517 | .XS | |
518 | Refer Bugs and Some Solutions | |
519 | .XE | |
520 | .PP | |
521 | The \fBrefer\fP program will mess up if there are blanks | |
522 | at the end of lines, especially the %A author line. | |
523 | \fBAddbib\fP carefully removes trailing blanks, | |
524 | but they may creep in again during editing. | |
525 | Use an editor command \*- | |
526 | .if n g/ *$/s/// \*- | |
527 | .if t g/\0\0\(**$/s/// \*- | |
528 | to remove trailing blanks from your bibliography. | |
529 | .PP | |
530 | Having bibliographic fields passed through as string definitions | |
531 | implies that interpolated strings (such as accent marks) | |
532 | must have two backslashes, so they can pass through copy mode intact. | |
533 | For instance, the word \*Qt\o'e\(aa'l\o'e\(aa'phone\*U | |
534 | would have to be represented: | |
535 | .DS | |
536 | te\e\e\(**\'le\e\e\(**\'phone | |
537 | .DE | |
538 | in order to come out correctly. | |
539 | In the %X field, by contrast, | |
540 | you will have to use single backslashes instead. | |
541 | This is because the %X field is not passed through as a string, | |
542 | but as the body of a paragraph macro. | |
543 | .PP | |
544 | Another problem arises from authors with foreign names. | |
545 | When a name like \*QVal\o"e\(aa"ry Giscard d'Estaing\*U | |
546 | is turned around by the \-a option of \fBrefer,\fP | |
547 | it will appear as \*Qd'Estaing, Val\o"e\(aa"ry Giscard,\*U | |
548 | rather than as \*QGiscard d'Estaing, Val\o"e\(aa"ry.\*U | |
549 | To prevent this, enter names as follows: | |
550 | .DS | |
551 | %A Vale\e\e\(**\'ry Giscard\e0d'Estaing | |
552 | %A Alexander Csoma\e0de\e0Ko\e\e\(**:ro\e\e\(**:s | |
553 | .DE | |
554 | (The second is the name of a famous Hungarian linguist.) | |
555 | The backslash-zero is an \fBnroff/troff\fP request | |
556 | meaning to insert a digit-width space. | |
557 | It will protect against faulty name reversal, | |
558 | and also against mis-sorting. | |
559 | .PP | |
560 | Footnote numbers are placed at the end of the line before the .[ macro. | |
561 | This line should be a line of text, not a macro. | |
562 | As an example, if the line before the .[ is a .R macro, | |
563 | then the .R will eat the footnote number. | |
564 | (The .R is an \-ms request meaning change to Roman font.) | |
565 | In cases where the font needs changing, | |
566 | it is necessary to do the following: | |
567 | .DS | |
568 | \efIet al.\efR | |
569 | \&.[ | |
570 | awk aho kernighan weinberger | |
571 | \&.] | |
572 | .DE | |
573 | Now the reference will be to Aho \fIet al\fR. | |
574 | .[ | |
575 | awk aho kernighan | |
576 | .] | |
577 | The \efI changes to italics, and the \efR changes back to Roman font. | |
578 | Both these requests are \fBnroff/troff\fP requests, not part of \-ms. | |
579 | If and when a footnote number is added after this sequence, | |
580 | it will indeed appear in the output. | |
581 | .SH | |
582 | Internal Details of Refer | |
583 | .XS | |
584 | Internal Details of Refer | |
585 | .XE | |
586 | .PP | |
587 | You have already read everything you need to know | |
588 | in order to use the \fBrefer\fP bibliography system. | |
589 | The remaining sections are provided only for extra information, | |
590 | and in case you need to change the way \fBrefer\fP works. | |
591 | .PP | |
592 | The output of \fBrefer\fP is a stream of string definitions, | |
593 | one for each field in a reference. | |
594 | To create string names, | |
595 | percent signs are simply changed to an open bracket, | |
596 | and an [F string is added, containing the footnote number. | |
597 | The %X, %Y and %Z fields are ignored; | |
598 | however, the \fBannobib\fP program changes the %X | |
599 | to an .AP (annotation paragraph) macro. | |
600 | The citation used above yields this intermediate output: | |
601 | .DS | |
602 | .ta \w'.ds\0'u +\w'[D\0'u | |
603 | \&.ds [F 1 | |
604 | \&.]- | |
605 | \&.ds [A Mike E. Lesk | |
606 | \&.ds [T Some Applications of Inverted Indexes on the Unix System | |
607 | \&.ds [J Unix Programmer's Manual | |
608 | \&.ds [I Bell Laboratories | |
609 | \&.ds [C Murray Hill, NJ | |
610 | \&.ds [D 1978 | |
611 | \&.ds [V 2a | |
612 | \&.nr [T 0 | |
613 | \&.nr [A 0 | |
614 | \&.nr [O 0 | |
615 | \&.][ 1 journal-article | |
616 | .DE | |
617 | These string definitions are sent to \fBnroff\fP, | |
618 | which can use the \-ms macros defined in /usr/lib/mx/tmac.xref | |
619 | to take care of formatting things properly. | |
620 | The initializing macro \fB.]\-\fP precedes the string definitions, | |
621 | and the labeled macro \fB.][\fP follows. | |
622 | These are changed from the input \fB.[\fP and \fB.]\fP so that | |
623 | running a file twice through \fBrefer\fP is harmless. | |
624 | .PP | |
625 | The \fB.][\fP macro, used to print the reference, | |
626 | is given a type-number argument, which is a numeric label | |
627 | indicating the type of reference involved. | |
628 | Here is a list of the various kinds of references: | |
629 | .DS | |
630 | .ta \w'Field\0\0\0'u +\w'Value\0\0'u | |
631 | Field Value Kind of Reference | |
632 | \l'\w'Field\0\0\0Value\0\0Kind of Reference\0'u' | |
633 | %J 1 Journal Article | |
634 | %B 3 Article in Book | |
635 | %R %G 4 Report, Government Report | |
636 | %I 2 Book | |
637 | %M 5 Bell Labs Memorandum (undefined) | |
638 | none 0 Other | |
639 | .DE | |
640 | The order listed above is indicative of the precedence | |
641 | of the various fields. | |
642 | In other words, a reference that has both the %J and %B fields | |
643 | will be classified as a journal article. | |
644 | If none of the fields listed is present, | |
645 | then the reference will be classified as \*Qother.\*U | |
646 | .PP | |
647 | The footnote number is flagged in the text with the following sequence, | |
648 | where \fInumber\fP is the footnote number: | |
649 | .DS | |
650 | \e*([.\fInumber\fP\e*(.] | |
651 | .DE | |
652 | The \e*([. and \e*(.] stand for bracketing or superscripting. | |
653 | In \fBnroff\fP with low-resolution devices such as the lpr and a crt, | |
654 | footnote numbers will be bracketed. | |
655 | In \fBtroff,\fP or on daisy-wheel printers, | |
656 | footnote numbers will be superscripted. | |
657 | Punctuation normally comes before the reference number; | |
658 | this can be changed by using the \-P (postpunctuation) | |
659 | option of \fBrefer\fP. | |
660 | .PP | |
661 | In some cases, it is necessary to override | |
662 | certain fields in a reference. | |
663 | For instance, each time a work is cited, | |
664 | you may want to specify different page numbers, | |
665 | and you may want to change certain fields. | |
666 | This citation will find the Lesk reference, | |
667 | but will add specific page numbers to the output, | |
668 | even though no page numbers appeared in the original reference. | |
669 | .DS | |
670 | \&.[ | |
671 | lesk inverted indexes | |
672 | %P 7-13 | |
673 | %I Computing Services | |
674 | %O UNX 12.2.2. | |
675 | \&.] | |
676 | .DE | |
677 | The %I line will also override any previous publisher information, | |
678 | and the %O line will append some commentary. | |
679 | The \fBrefer\fP program simply adds | |
680 | the new %P, %I, and %O strings to the output, | |
681 | and later strings definitions cancel earlier ones. | |
682 | .PP | |
683 | It is also possible to insert an entire citation | |
684 | that does not appear in the bibliographic database. | |
685 | This reference, for example, could be added as follows: | |
686 | .DS | |
687 | \&.[ | |
688 | %A Brian Kernighan | |
689 | %T A Troff Tutorial | |
690 | %I Bell Laboratories | |
691 | %D 1978 | |
692 | \&.] | |
693 | .DE | |
694 | This will cause \fBrefer\fP to interpret the fields exactly as given, | |
695 | without searching the bibliographic database. | |
696 | This practice is not recommended, however, because it's better | |
697 | to add new references to the database, so they can be used again later. | |
698 | .PP | |
699 | If you want to change the way footnote numbers are printed, | |
700 | signals can be given on the \fB.[\fP and \fB.]\fP lines. | |
701 | For example, to say \*QSee reference (2),\*U | |
702 | the citation should appear as: | |
703 | .DS | |
704 | See reference | |
705 | \&.[( | |
706 | partial citation | |
707 | \&.]), | |
708 | .DE | |
709 | Note that blanks are significant on these signal lines. | |
710 | If a permanent change in the footnote format is desired, | |
711 | it's best to redefine the \fB[.\fP and \fB.]\fP strings. | |
712 | .SH | |
713 | Changing the Refer Macros | |
714 | .XS | |
715 | Changing the Refer Macros | |
716 | .XE | |
717 | .PP | |
718 | This section is provided for those who wish to rewrite | |
719 | or modify the \fBrefer\fP macros. | |
720 | This is necessary in order to make output correspond | |
721 | to specific journal requirements, or departmental standards. | |
722 | First there is an explanation of how new macros | |
723 | can be substituted for the old ones. | |
724 | Then several alterations are given as examples. | |
725 | Finally, there is an annotated copy of | |
726 | the \fBrefer\fP macros used by \fBroffbib\fP\|. | |
727 | .PP | |
728 | The \fBrefer\fP macros for \fBnroff/troff\fP supplied by | |
729 | the \-ms macro package reside in /usr/lib/mx/tmac.xref; | |
730 | they are reference macros, for producing footnotes or endnotes. | |
731 | The \fBrefer\fP macros used by \fBroffbib,\fP | |
732 | on the other hand, reside in /usr/lib/tmac/tmac.bib; | |
733 | they are for producing a stand-alone bibliography. | |
734 | .PP | |
735 | To change the macros used by \fBroffbib,\fP | |
736 | you will need to get your own version of this shell script | |
737 | into the directory where you are working. | |
738 | These two commands will get you a copy of \fBroffbib\fP | |
739 | and the macros it uses: \(dg | |
740 | .DS | |
741 | % \fBcp /usr/lib/tmac/tmac.bib bibmac\fP | |
742 | .DE | |
743 | You can proceed to change bibmac as much as you like. | |
744 | Then when you use \fBroffbib\fP, | |
745 | you should specify your own version of the macros, | |
746 | which will be substituted for the normal ones | |
747 | .DS | |
748 | % \fBroffbib \-m bibmac\fR \fIfilename\fP | |
749 | .DE | |
750 | where \fIfilename\fP is the name of your bibliography file. | |
751 | Make sure there's a space between \-m and \fBbibmac\fP. | |
752 | .PP | |
753 | If you want to modify the \fBrefer\fP macros | |
754 | for use with \fBnroff\fP and the \-ms macros, | |
755 | you will need to get a copy of \*Qtmac.xref\*U: | |
756 | .DS | |
757 | % \fBcp /usr/lib/ms/s.ref refmac\fP | |
758 | .DE | |
759 | These macros are much like \*Qbibmac\*U, | |
760 | except they have .FS and .FE requests, | |
761 | to be used in conjunction with the \-ms macros, | |
762 | rather than independently defined .XP and .AP requests. | |
763 | Now you can put this line at the top of the paper to be formatted: | |
764 | .DS | |
765 | \&.so refmac | |
766 | .DE | |
767 | Your new \fBrefer\fP macros will override the definitions | |
768 | previously read in by the \-ms package. | |
769 | This method works only if \*Qrefmac\*U is in the working directory. | |
770 | .PP | |
771 | Suppose you didn't like the way dates are printed, | |
772 | and wanted them to be parenthesized, with no comma before. | |
773 | There are five identical lines you will have to change. | |
774 | The first line below is the old way, | |
775 | while the second is the new way: | |
776 | .DS | |
777 | \&.if !"\e\e*([D"" , \e\e*([D\ec | |
778 | \&.if !"\e\e*([D"" \e& (\e\e*([D)\ec | |
779 | .DE | |
780 | In the first line, there is a comma and a space, but no parentheses. | |
781 | The \*Q\ec\*U at the end of each line | |
782 | indicates to \fBnroff\fP that it should continue, | |
783 | leaving no extra space in the output. | |
784 | The \*Q\e&\*U in the second line is the do-nothing character; | |
785 | when followed by a space, a space is sent to the output. | |
786 | .PP | |
787 | If you need to format a reference in the style | |
788 | favored by the Modern Language Association | |
789 | or Chicago University Press, | |
790 | in the form (city: publisher, date), | |
791 | then you will have to change the middle of | |
792 | the book macro [2 as follows: | |
793 | .DS | |
794 | \e& (\ec | |
795 | \&.if !"\e\e*([C"" \e\e*([C: | |
796 | \e\e*([I\ec | |
797 | \&.if !"\e\e*([D"" , \e\e*([D\ec | |
798 | )\ec | |
799 | .DE | |
800 | This would print (Berkeley: Computing Services, 1982) | |
801 | if all three strings were present. | |
802 | The first line prints a space and a parenthesis; | |
803 | the second prints the city (and a colon) if present; | |
804 | the third always prints the publisher | |
805 | (books must have a publisher, or else they're classified as other); | |
806 | the fourth line prints a comma and the date if present; | |
807 | and the fifth line closes the parentheses. | |
808 | You would need to make similar changes to the other macros as well. | |
809 | .SH | |
810 | Acknowledgements | |
811 | .XS | |
812 | Acknowledgements | |
813 | .XE | |
814 | .PP | |
815 | Mike Lesk of Bell Laboratories wrote the original \fBrefer\fP software, | |
816 | including the indexing programs. | |
817 | Al Stangenberger of the Forestry Department | |
818 | wrote the first version of \fBaddbib\fP, then called \fBbibin\fP. | |
819 | Greg Shenaut of the Linguistics Department | |
820 | wrote the original versions of \fBsortbib\fP and \fBroffbib\fP. | |
821 | All these contributions are greatly appreciated. | |
822 | .nr Pg \n(PN+1 | |
823 | .XS \n(Pg | |
824 | Commented Refer Macros | |
825 | .XE | |
826 | .nr LL 6i | |
827 | .TC |