![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to refer.bib CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 29.refer|
Return to refer.bib CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 29.refer |
1.1 root 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: .\"
5: .\" @(#)refer.bib 6.1 (Berkeley) 6/2/86
6: .\"
7: .EH 'USD:29-%''Refer \(em A Bibliography System'
8: .OH 'Refer \(em A Bibliography System''USD:29-%'
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: ..
17: .\".RP
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
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.