![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prefer.m CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / vol2 / prefer|
Return to prefer.m CVS log | Up to [Research Unix] / researchv10dc / vol2 / prefer |
1.1 root 1: |make(rp)
2:
3: |insert(../monk/monk.mac)
4:
5:
6: |comment(VOL2HEADER)|set_counter(page 163-1)|set_string(page_headers "'''")|set_string(even_headers "'Formatting References with Prefer''\f(NIprefer\fP'")|set_string(odd_headers "'\f(NIprefer\fP''Formatting References with Prefer'")|set_string(even_footers "_\\nP__UNIX Papers_")|set_string(odd_footers "'Research Tenth Edition''\\nP'")
7: |author(name "M. A. Derr", initials MAD, location MH, department 11225,
8: extension x4721, room 2D-455)
9:
10: |date(July 1, 1989)
11: |title(Formatting References with Prefer)
12:
13: |begin(abstract)
14: |i(Prefer) is a |small(UNIX) text processing
15: tool
16: that formats bibliographic references.
17: Using a bibliography database, it scans a document to
18: convert symbolic references
19: to citation marks and full references ready for typesetting.
20: It currently supports a variety of reference formatting
21: styles including those of the |s(ACM), |s(IEEE), and |s(APA).
22: |i(Prefer)
23: runs as a preprocessor to |i(troff)
24: and can also be invoked by
25: the |i(monk) text processing package.
26: This paper describes |i(prefer) and its supporting
27: tools for creating, indexing,
28: and retrieving from bibliography databases and for
29: converting |i(refer)-style databases and documents
30: for use with |i(prefer).
31: |end(abstract)
32:
33:
34: |titlebox
35:
36: |insert(prefer.cite)
37:
38: |style(two_column)
39:
40: |section(Introduction)
41:
42: |i(Prefer) is a |small(UNIX) text processing
43: tool|dagnote[In addition to
44: Tenth Edition |small(UNIX),
45: |i(prefer) runs under
46: |small(AT&T UNIX) System V
47: and 4.3|small(BSD UNIX).]
48: that formats bibliographic references.
49: Using a bibliography database, it scans a document to
50: convert symbolic references
51: to citation marks and full references ready for typesetting.
52: Like |i(eqn)|reference(latest eqn) and
53: |i(tbl)|reference(latest tbl), |i(prefer)
54: runs as a preprocessor to |i(troff)
55: |reference(latest troff tutorial).
56: It can also be invoked by
57: the |i(monk)|reference(latest monk) text processing package.
58:
59: |p
60: |i(Prefer) was designed to replace the |i{refer}
61: |reference{Lesk indexes} bibliography program.
62: |i(Refer) is not only lacking in flexibility, with much of
63: its functionality hardwired into C code,
64: but the code is difficult to modify and maintain.
65: |i(Prefer) improves on
66: |i{refer} and
67: on |i{bib} |reference{bib}, an earlier
68: |i{refer} replacement.
69: It also follows style conventions found in
70: other bibliography formatters such as |i{Scribe} |reference{scribe},
71: and |i{BibTeX} |reference{latex} |reference{bibtex}.
72: It attains flexibility by encoding all style-dependent formatting
73: information in scripts written in |i{awk} |reference{awk 1988},
74: a pattern scanning and processing language.
75: |i{Prefer} currently supports seven reference formatting styles:
76:
77: |environment(text_list;
78: list.pre "\&", list.format 1,
79: list.post "\ ",
80: if "@\*(l5@@",
81: set string l5 "nnnnnn",
82: store width l2 l5,
83: tab.stops "\n(l2u",
84: list.spacing off, list on;
85:
86: list off, tab.stops,
87: )
88: |comment<summary: text_list (text list using text from item))>
89:
90:
91: |associate(item;
92: store string Ts l2;
93:
94: |ifvalue list.spacing on [
95: blank.lines 6p,
96: ]
97: store width l2 l5,
98: store width l1 Ts,
99: if else "\n(l1>\n(l2",
100: add string.from.string Ts l4,
101: if else,
102: add string Ts " ",
103: store string Rs l4,
104: indent.line 0,
105: string Ts, concatenate;
106: [$;;
107: add string Ts $])
108: |comment<summary: item (item of a list; IT)>
109:
110: |blank_space(6p)
111: .ds l5 |cw<spectrum>n
112: |begin(text_list)
113: |item{"\f(CWatt\fP"}|small(AT&T) Bell Laboratories
114: |item{"\f(CWacm\fP"}Association for Computing Machinery
115: |item{"\f(CWapa\fP"}American Psychological Association
116: |item{"\f(CWieee\fP"}Institute of Electrical and Electronics Engineers, Inc.
117: |item{"\f(CWlsa\fP"}Linguistic Society of America
118: |item{"\f(CWpami\fP"}Pattern Analysis and Machine Intelligence
119: |item{"\f(CWspectrum\fP"}|small(IEEE) Spectrum
120: |end(text_list)
121: In addition, users may define their own styles
122: by supplying an appropriate |i{awk} style script.
123: |i{Prefer} uses the |cw{att} style by default.
124: Unless noted, all examples in this paper will be
125: in |cw{att} style.
126:
127: |p
128: To give a flavor of what |i(prefer) can do, here is
129: a simple example of a document containing citations to
130: references in a bibliography database.
131: At the end of the document, the full references are printed.
132: Here's the document before it is formatted:
133:
134: |begin(here)
135: |begin(figure)
136: |begin(figsmall)
137: |insert(example/simple.in)
138: |end(figsmall)
139: |end(figure)
140: |end(here)
141:
142: The command |cw<|sp(|s)reference(awk)> tells |i(prefer)
143: to search a bibliography database for a reference containing
144: the word ``awk,'' somewhere
145: in a database entry, e.g, in the author or title field.
146: |i(Prefer) will replace
147: the |cw<|sp(|s)reference>
148: command with a citation mark that corresponds
149: to the matching reference.
150: References from each |cw<|sp(|s)reference>
151: command are remembered by |i(prefer).
152: When |i(prefer) reaches the |cw<|sp(|s)reference_placement>
153: command, references seen so far are formatted
154: according to the current style.
155: When the above document (in a file called
156: |cw(document)) is run through |i(prefer)
157: and |i(troff):
158:
159: |figure<|small{|cw(prefer document | troff) |i(-options) |cw(...)}>
160:
161: the following output is produced:
162:
163: |p
164: |begin(here)
165: |begin(figsmall)
166: |source(example/simple.t)
167: |end(figsmall)
168: |end(here)
169:
170: |p
171: In addition to the |i{prefer} program,
172: several other support tools are available.
173: |i(Penter)
174: is an interactive tool for creating
175: or appending to bibliography databases.
176: |i(Pinvert) creates an index to the bibliography database for fast retrieval.
177: |i(Plook) retrieves entries that match search keywords
178: from a bibliography database.
179: |i(Pconvert) converts |i(refer)-style documents and databases to
180: |i(prefer)-style.
181: The remainder of this
182: paper describes |i(prefer) and its supporting tools
183: and provides
184: examples of their use.
185:
186: |section(Bibliographic Database)
187: A bibliography database is a file consisting of
188: one or more entries separated by newlines.
189: Each entry is composed of several %attribute/value pairs
190: providing such information as type, author, title, and date.
191: For example, here is an entry describing the |i(awk) book
192: referenced in the previous example.
193:
194: |begin(here)
195: |begin(figure)
196: |begin(figsmall)
197: %type book
198: %author Alfred V. Aho
199: %author Brian W. Kernighan
200: %author Peter J. Weinberger
201: %title The |small(AWK) Programming Language
202: %publisher Addison-Wesley
203: %address Reading, Massachusetts
204: %date 1988
205: |end(figsmall)
206: |end(figure)
207: |end(here)
208:
209: Appendix |remember{types}
210: provides a complete list of types and
211: attributes.
212:
213: |subsection{Building a Bibliography}
214: You may create or modify a bibliography database using your
215: favorite text editor or by using the tool,
216: |i{penter}.|starnote<|i(Penter) is based on a program
217: written by T.J. Kowalski and H. H. Goguen.>
218: After invoking |i{penter} with the name of the bibliography file
219: as the argument (|cw[prefer.out] by default),
220: |i{penter} prompts for a reference type.
221: Typing |cw<?> to this prompt
222: gets you a list of legal types.
223: Typing |cw<help> to the same prompt will get
224: you a subprompt for a reference type who's attributes
225: will be listed. Answering |cw<?> to this subprompt
226: will list attributes for each type.
227: |p
228: Each reference type has some required attributes and some optional
229: attributes.
230: After you respond to the initial reference type prompt
231: with a legal type, |i(penter) prompts for each
232: attribute associated with that type.
233: Some attributes have
234: default values, shown in brackets, |cw([) |i(default) |cw(]).
235: Defaults may be accepted
236: by typing a return, skipped by typing spaces before
237: the return, or overridden by typing a new value.
238: For attributes without defaults,
239: typing a value followed by return
240: enters that value, while typing return, skips the attribute.
241: Required attributes may not be skipped.
242: The character |cw<&> appended to an attribute value
243: causes the prompt for the current attribute to be repeated.
244: This allows multiple authors or editors to be entered
245: or allows titles to span multiple lines, for example.
246: |p
247: When |i{penter} is finished with an entry, it
248: begins again, prompting for another reference type.
249: To terminate a |i{penter} session, type |cw<quit> and
250: the new entries will be written to the bibliography file.
251: This example shows how to enter the previous reference
252: using |i(penter); the result is put in the file |cw(prefer.out).
253: |i(Penter)'s prompts are in |i(italics).
254:
255: |begin(here)
256: |begin(figure)
257: |begin(figsmall)
258: |cw(penter)
259: |i(Reference type [article]) |cw(book)
260: |i(author:) |cw(Alfred V. Aho&)
261: |i(author:) |cw(Brian W. Kernighan&)
262: |i(author:) |cw(Peter J. Weinberger)
263: |i(title:) |cw(The AWK Programming Language)
264: |i(publisher:) |cw(Addison-Wesley)
265: |i(date: 1988)
266: |i(volume:)
267: |i(other:)
268: |i(also:)
269: |i(keywords:)
270: |i(location status [don't have]:)
271: |i(read status [haven't read]:)
272: |i(comments:)
273: |i(Reference type [article]) |cw(quit)
274: |end(figsmall)
275: |end(figure)
276: |end(here)
277: .............
278: |p
279: If you want to modify
280: the current entry, respond to the current prompt with |cw<~v>
281: to invoke a visual editor (|cw($VISUAL)
282: if set, or |i(vi) if not)
283: or |cw<~e> to invoke
284: a line editor (|cw($EDITOR) if set, or |i(ed) if not).
285: After making some changes and
286: leaving the editor, you will be back in |i{penter} at the same
287: point where you left off.
288: Alternatively, you can modify the bibliography
289: file with a text editor after you have exited |i(penter).
290:
291: |subsubsection(Author and editor names.)
292: Proper names may be entered in a variety of ways;
293: |i(prefer) knows how to figure out first names, initials, last names,
294: titles, etc.
295: It also knows about some two part last names such as
296: De Paul and Van Winkle.
297: For example, any of the following are acceptable ways to enter
298: a name.
299:
300: |begin(here)
301: |begin(figure)
302: |begin(figsmall)
303: %author John Thomas De Paul
304: %author Dr. John T. De Paul, Jr.
305: %editor J. T. De Paul Jr.
306: %editor De Paul, John T., Jr
307: |end(figsmall)
308: |end(figure)
309: |end(here)
310: |p
311: If you use the name of an organization or
312: corporation as an author or editor and do
313: not want |i(prefer) to parse it as the name
314: of a person, enclose the name in the |cw(%verbatim) command.
315: This command is also useful in keeping
316: double last names together.
317: Here are two examples:
318: |begin(here)
319: |begin{figure}
320: |begin(figsmall)
321: %author %verbatim(|small[AT&T] Bell Laboratories)
322: %author John %verbatim(Smith Jones)
323: |end(figsmall)
324: |end{figure}
325: |end(here)
326:
327: |subsubsection(The \f(CW%also\fP attributes.)
328:
329: Another class of attributes deserves special mention.
330: The |cw(%also) attributes allow one bibliographic reference
331: to refer by keyword to another reference contained in the
332: same database as this example shows:
333:
334: |comment(replace this reference with something more relevant and shorter; maybe put formatted version in examples section)
335: |begin(here)
336: |begin(figure)
337: |begin(figsmall)
338: |insert(example/hirst)
339: |end(figsmall)
340: |end(figure)
341: |end(here)
342:
343: When a reference to the first entry is formatted,
344: both references will appear in a single entry.
345: |begin(here)
346: |begin(figsmall)
347: |source(example/hirst.t)
348: |end(figsmall)
349: |end(here)
350:
351: |p
352: Two other attributes,
353: |cw(%also_begin) and |cw(%also_end), can enclose
354: another |cw(%also) attribute,
355: surrounding it with optional text
356: 'ne 2v
357: as this example demonstrates:
358: |begin(here)
359: |begin(figure)
360: |begin(figsmall)
361: %also_begin (See also
362: %also Grosz Sparck Jones Webber
363: %also_end )
364: |end(figsmall)
365: |end(figure)
366: |end(here)
367: Alternatively, a partial or complete reference may be included between
368: |cw(%also_begin) and |cw(%also_end):
369:
370: |begin(here)
371: |begin(figure)
372: |begin(figsmall)
373: %also_begin Reprinted in
374: %type editedbook
375: %title Programming Languages: A Grand Tour
376: %editor Ellis Horowitz
377: %date 1983
378: %publisher Computer Science Press
379: %address Rockville, MD
380: %also_end
381: |end(figsmall)
382: |end(figure)
383: |end(here)
384: While |cw(%also) is supported by |i{penter},
385: |cw(%also_begin) and |cw(%also_end) are not and must
386: be entered using a text editor.
387: .......
388:
389: |subsection(Indexing a Bibliography)
390:
391: |i(Pinvert)|dagnote<Based on the |i(bib)|reference(bib) version
392: by T. A. Budd>
393: creates a search key
394: index to one or more bibliography database files.
395: Indexing the database lets you refer to any
396: entry using a unique combination of search keys.
397: To create the index, |i(pinvert) uses words of at least
398: three characters found the bibliography.
399: Some common words (those found in |cw</usr/lib/eign>)
400: are ignored.
401: In addition, values of some of the attributes
402: are ignored (|cw(%volume) and |cw(%pages), for example).
403: |i(Pinvert) converts all keys to lower case, removes
404: non-alphanumeric characters, and truncates
405: each key to six characters.
406: |p
407: |i(Pinvert) with no arguments, assumes that the bibliography
408: file is |cw(prefer.out) and stores the index and header information in
409: |cw(prefer.out.i) and |cw(prefer.out.h).
410: If more than one file is being indexed,
411: the index is named after the first file
412: in the list.
413: For example,
414:
415: |figure<|small(|cw{pinvert ourbib theirbib mybib})>
416:
417: creates an index to all three bibliography files,
418: storing the index and header information
419: in |cw(ourbib.i) and |cw(ourbib.h), respectively.
420: Alternatively, index and header files can also be given a
421: unique name using
422: the |cw(-p) option:
423:
424: |figure(|small<|cw{pinvert \-p index yours mine ours}>)
425:
426: stores the index and header files
427: for the three bibliography files in |cw(index.i) and |cw(index.h).
428:
429: |p
430: |i(Pinvert) provides several other options.
431: .ds l5 |cw(\-k) |i(maxkey)n
432: |begin(text_list)
433: |blank_space(1)
434: |item{"\f(CW\-c\fP \fIcfile\fP"}specifies a file
435: of common words, one per line,
436: to exclude as indexing keys
437: (default is |cw(/usr/lib/eign)).
438: |blank_space(1)
439: |item{"\f(CW\-i\fP \fIifile\fP"}specifies a file
440: of attributes, one per line,
441: to ignore while collecting
442: keys from database entries.
443: The default file, |cw(/usr/lib/prefer/ignore),
444: contains the attributes |cw(%volume), |cw(%number),
445: |cw(%part), |cw(%pages), |cw(%also), |cw(%X), |cw(%Y), and |cw(%Z).
446: |blank_space(1)
447: |item{"\f(CW\-k\fP \fImaxkey\fP"}specifies the maximum number
448: of search keys
449: collected per reference (default is 100 keys).
450: |blank_space(1)
451: |item{"\f(CW\-l\fP \fIkeylen\fP"}specifies the maximum length of a search
452: key(default is 6 characters).
453: |blank_space(1)
454: |item{"\f(CW\-v\fP"}tells |i(pinvert) to print statistics.
455: |end(text_list)
456:
457: |subsection<Retrieval by Keyword>
458:
459: |i(Plook) is a command that uses an index
460: to search a bibliography database for references
461: that match search keys.
462: As in |i(pinvert),
463: search keys are a sequence of non-white space characters
464: with non-alphanumeric characters removed.
465: Keys must be at least three characters and are
466: converted to lower-case and truncated to six characters.
467: Some common words are ignored (those in the file |cw</usr/lib/eign>
468: by default).
469: If the search keys appear on the command line, |i(plook) retrieves
470: all references that contain all the search keys
471: and prints the references on
472: the standard output.
473: For example,
474:
475: |figure<|small(|cw{plook awk book})>
476:
477: would output:
478:
479: |begin(here)
480: |begin(figure)
481: |begin(figsmall)
482: |begin(i)
483: %type book
484: %author Alfred V. Aho
485: %author Brian W. Kernighan
486: %author Peter J. Weinberger
487: %title The AWK Programming Language
488: %publisher Addison-Wesley
489: %address Reading, Massachusetts
490: %date 1988
491: |end(i)
492: |end(figsmall)
493: |end(figure)
494: |end(here)
495:
496: If the command line contains no search keys,
497: then |i(plook) reads a line of standard input for search keys.
498: After returning the matching reference(s) it waits for
499: the next line of keys, terminating when it receives
500: an end-of-file character, <|b(control-d)>.
501: Here's an example of this mode of use:
502:
503: |begin(here)
504: |begin(figure)
505: |begin(figsmall)
506: |cw(plook)
507: |cw(lesk indexes)
508: |begin(i)
509: %type incollection
510: %author M. E. Lesk
511: %title Some Applications of Inverted Indexes
512: on the UNIX System
513: %booktitle UNIX Programmer's Manual,
514: Seventh Edition
515: %publisher Bell Laboratories
516: %address Murray Hill, NJ
517: %date January, 1979
518: %volume 2A
519: |end(i)
520:
521: |cw(lesk tables)
522: |begin(i)
523: %type incollection
524: %author M. E. Lesk
525: %title TBL \- A program to format tables
526: %booktitle UNIX Text Editing & Phototypesetting
527: Starter Package
528: %editor Claudine Tartanella
529: %publisher Computing Information Services,
530: Bell Laboratories
531: %address Murray Hill, NJ
532: %date 1980
533: |end(i)
534:
535: |cw(<control-d>)
536: |end(figsmall)
537: |end(figure)
538: |end(here)
539:
540: |p
541: |i(Plook)
542: recognizes the options |cw<-c>, |cw<-l>, and |cw<-p>
543: with the same meanings as |i(pinvert).
544: If the index file is out of date or does not exist,
545: |i(plook) will try to create it by invoking |i(pinvert).
546:
547: |section(Formatting References In Documents)
548:
549: This section explores in detail the |i(prefer) program
550: for formatting documents with bibliographic references.
551: |i(Prefer) scans a text file looking for one
552: of the following commands to process:
553:
554: |begin(here)
555: |begin(figure)
556: |cw<|sp(|s)reference( |i[keywords... attributes... flags...] )>
557: |cw<|sp(|s)reference_placement>
558: |cw<|sp(|s)reference_include( |i[dbfile...] )>
559: |cw<|sp(|s)reference_database( |i[dbfile] )>
560: |cw<|sp(|s)reference_list( |i[dbfile...] )>
561: |cw<|sp(|s)reference_style( |i(style [arg...] ))>
562: |end(figure)
563: |end(here)
564:
565: Each will be described in turn.
566: The parentheses enclosing the command arguments
567: may be replaced by the |cw({}), |cw([]), or |cw(<>).
568: |i(Prefer) also accepts several command line options
569: that are explained at the end of this section.
570:
571: |subsection(Citations)
572:
573: The |cw<|sp(|s)reference>
574: command is for citing reference within a text.
575: As you saw in the introduction and in the
576: following example, you can cite a reference using
577: keywords which |i(prefer) will use
578: to search a bibliography database for a matching entry.
579:
580: |figure<|small[|cw{... sort methods|reference(Knuth Art 1973) ...}]>
581:
582: Keywords should be chosen so as to uniquely identify
583: a particular reference.
584: You can use words from any attribute
585: not ignored by |i(pinvert), including
586: |cw(%author), |cw(%title), |cw(%keyword) and |cw(%date).
587: If multiple references match the keys,
588: |i(prefer) will print a warning,
589: but use only the first match.
590: Similarly, if no references match, a warning message is printed.
591: If two or more references in the database share all possible search keys,
592: you can add extra words to the |cw(%keyword) attribute of each
593: entry in the database to
594: distinguish among them.
595:
596: |p
597: In addition to keyword search, you can cite
598: a reference by including
599: the entire reference in the command as shown
600: below.
601: Note that subsequent references to this reference
602: will have to respecify all the attributes.
603: |begin(here)
604: |begin(figure)
605: |begin(figsmall)
606: |sp(|s)reference(
607: %type book
608: %author Donald E. Knuth
609: %title The Art of Computer Programming
610: %volume Volume 3/Sorting and Searching
611: %publisher Addison-Wesley
612: %keywords sorting searching
613: %address Reading, MA
614: %date 1973
615: )
616: |end(figsmall)
617: |end(figure)
618: |end(here)
619: |p
620: A third way is to use keywords to select a database reference,
621: followed by attributes
622: that supplement or override attributes
623: in the database reference.
624: For example, a keyword selected reference could
625: be supplemented with a |cw(%also) entry as shown below.
626: |begin(here)
627: |begin(figure)
628: |begin(figsmall)
629: |sp(|s)reference(
630: McKeown phdthesis
631: %also_begin Also in
632: %type techreport
633: %publisher University of Pennsylvania
634: %date 1982
635: %report Technical Report MS-CIS-82-5
636: %also_end
637: )
638: |end(figsmall)
639: |end(figure)
640: |end(here)
641: In all cases, |i(prefer)
642: replaces the citation command with
643: a citation mark that corresponds
644: to the full reference as it appears in the list
645: formatted by the |cw<|sp(|s)reference_placement>
646: command.
647: The |cw(att), |cw(ieee), and |cw(spectrum) styles
648: use superscripted numbers for citation marks;
649: |cw(acm) and |cw(pami) styles use numbers in square brackets;
650: |cw(apa) and |cw(lsa) styles use (author, year).
651:
652: |p
653: Following keywords and attributes, you can supply
654: flags that
655: modify the citation mark.
656: The citation flags, |cw(%no_author) and |cw(%no_date),
657: relevant to |cw(att) and |cw(lsa) styles,
658: cause the author field and date field, respectively, to be excluded
659: from the citation mark.
660: The |cw(%no_cite) flag, relevant to all styles, causes the entire citation to be
661: omitted, but the full reference is still printed in the list of
662: references.
663: Some styles
664: let you annotate a citation with text
665: using |cw(%pre_text) and |cw(%post_text).
666: Annotations could include introductory phrases
667: and page numbers, for example.
668: If multiple citation flags are used (e.g, both |cw(%no_author)
669: and |cw(%post_text)),
670: each must appear on it's own line.
671: Formatting the following document fragment in |cw(apa) style
672: |begin(here)
673: |begin(figure)
674: |begin(figsmall)
675: |insert(example/lamport.in)
676: |end(figsmall)
677: |end(figure)
678: |end(here)
679: produces this output:
680: |begin(here)
681: |begin(figure)
682: |begin(figsmall)
683: |source(example/lamport.t)
684: |end(figsmall)
685: |end(figure)
686: |end(here)
687:
688: More uses of |cw<|sp(|s)reference> are found in
689: Appendix |remember(examples).
690:
691: |subsection(Reference Placement)
692:
693:
694: The |cw<|sp(|s)reference_placement> command causes all
695: references seen since the beginning of the document,
696: the last |cw<|sp(|s)reference_placement>,
697: or the last |cw<|sp(|s)reference_style> command,
698: to be formatted and inserted in the document at that point.
699: The order of references depends on the current style.
700: References in |cw(att), |cw(ieee), and |cw(spectrum) styles
701: appear in the order first cited in the preceding text.
702: References in |cw(acm), |cw(apa), |cw(lsa), and |cw(pami) are sorted by
703: author, date, and title.
704: All except |cw(apa) and |cw(lsa)
705: have labels that match the citation
706: marks appearing in the text.
707: |p
708: See Appendix |remember(examples) for uses
709: and results of |cw<|sp(|s)reference_placement>.
710:
711:
712: |subsection(Including Additional References)
713: Sometimes you may want the reference list
714: to include more references than you actually
715: cite in the text.
716: The |cw<|sp(|s)reference_include( |i[dbfile...] )> command
717: includes the contents of one or more database files
718: in the list of references produced by
719: |cw<|sp(|s)reference_placement>, treating
720: them as |cw(%no_cite) entries.
721: For example, the |cw<|sp(|s)reference_placement>
722: command here:
723:
724: |begin(here)
725: |begin(figure)
726: |begin(figsmall)
727: |i(text with citations)
728: ...
729: |sp(|s)reference_include(morebibs)
730: |sp(|s)reference_placement
731: |end(figsmall)
732: |end(figure)
733: |end(here)
734:
735: will include in its list
736: of references all the entries in the file |cw(morebibs)
737: as well as
738: any citations found in the text.
739:
740: |subsection(Switching Databases)
741:
742: The command to search a new bibliography database is
743: |cw<|sp(|s)reference_database( |i[dbfile] )>.
744: |i(Prefer) then closes the current
745: database file, and opens the new one, |i(dbfile).
746: But it still remembers citations from the previous
747: database.
748: For example, in
749:
750: |begin(here)
751: |begin(figure)
752: |begin(figsmall)
753: |sp(|s)reference_database(mybib1)
754: |i(text with citations)
755: ...
756: |sp(|s)reference_database(mybib2)
757: |i(text with more citations)
758: ...
759: |sp(|s)reference_placement
760: |end(figsmall)
761: |end(figure)
762: |end(here)
763:
764: the first database, |cw(mybib1),
765: is consulted for the first part of the text,
766: while the database |cw(mybib2) is consulted
767: for the second part.
768: The |cw<|sp(|s)reference_placement> command
769: will list citations from both databases.
770: |p
771: All databases should be indexed using |i(pinvert).
772: However, if a database has not been indexed since its last update,
773: |i(prefer) will automatically
774: invoke |i(pinvert) before using the database.
775:
776: |subsection(Complete Bibliographies)
777:
778: Beside formatting references appearing in documents,
779: |i(prefer) also formats entire bibliography databases.
780: The command |cw<|sp(|s)reference_list( |i[dbfile...] )>,
781: behaves like |cw<|sp(|s)reference_placement>
782: except that instead of formatting citations appearing
783: in the previous text, it formats
784: all the references appearing in one or more bibliography
785: databases.
786: For example,
787:
788: |figure<|small[|sp(|s)reference_list(mybib88 mybib89)]>
789:
790: produces a list of all references in the file |cw(mybib88)
791: followed by all references in |cw(mybib89).
792: |p
793: Like |cw<|sp(|s)reference_database>,
794: this command changes the search database.
795: The current style dictates how each entry will be formatted.
796: By default, the entries will be printed
797: in the order they appear in the database(s).
798: Changing this order requires
799: setting some style arguments or
800: supplying some command line options.
801: Both ways are described below.
802:
803:
804: |subsection(Styles Options)
805: |save(stylesec)
806: The |cw<|sp(|s)reference_style( |i(style [arg...] ))> command provides one way
807: to change options regarding formatting style.
808: The first argument to this command selects
809: the style script.
810: It gives the name of one of
811: the styles provided by prefer
812: (|cw(att), |cw(acm), |cw(apa), |cw(ieee), |cw(spectrum), |cw(lsa)
813: or |cw(pami)), or the pathname of
814: a user-defined style script.
815: Note that any file in the current directory with the same
816: name as one of the |i(prefer) styles (e.g. |cw(acm)),
817: will override the |i(prefer) style.
818: The easiest way to define a new style is
819: to modify an existing |i{awk} style script that is similar
820: to the desired style.
821: Describing how to write a style script in further detail is
822: beyond the scope of this paper.
823: |p
824: Your document may use multiple formatting styles
825: by resetting the style using |cw<|sp(|s)reference_style>.
826: If you switch styles before issuing a |cw<|sp(|s)reference_placement>
827: command, the citations appearing before the style command
828: will be forgotten and thus,
829: will not be listed by any subsequent |cw<|sp(|s)reference_placement>.
830: |p
831: Some of the optional arguments to the style command control
832: how references
833: are formatted by the |cw<|sp(|s)reference_list> command.
834: |begin(here)
835: |begin(table)
836: center;
837: l l.
838: |cw(sequence) list in database order
839: |cw(sort) list according to current style
840: |cw(a) sort by author
841: |cw(d) sort by date
842: |cw(t) sort by title
843: |end(table)
844: |end(here)
845: The last three options may be used in combination.
846: If optional arguments are given, but the
847: style is to remain the same, the first
848: argument may be set to |cw(same).
849: |p
850: The style command recognizes several other
851: arguments that affect the formatting of references.
852: These are:
853: |begin(here)
854: |begin(table)
855: center;
856: l l.
857: |cw(tm) format as a technical memorandum
858: |cw(rp) format as a released paper
859: |cw(troff) format for |i(troff)
860: |cw(nroff) format for |i(nroff)
861: |end(table)
862: |end(here)
863: The defaults are for a paper to be formatted
864: as a technical memorandum using |i(troff)
865: Here are some examples of using the style command:
866: |begin(here)
867: |begin(figure)
868: |begin(figsmall)
869: |begin(cw)
870: |sp(|s)reference_style(/usr/mad/mystyle ad)
871: |sp(|s)reference_list(bib)
872: |sp(|s)reference_style(acm sort rp)
873: |sp(|s)reference_list(bib)
874: |sp(|s)reference_style(same sequence nroff)
875: |sp(|s)reference_list(bib)
876: |end(cw)
877: |end(figsmall)
878: |end(figure)
879: |end(here)
880:
881: The first command selects the user-defined style
882: in |cw(/usr/mad/mystyle) and says to sort according
883: to author, then date.
884: The bibliography file |cw(bib) is formatted accordingly.
885: The third command selects the |cw(acm) style,
886: and says to sort |cw(bib) according to that style.
887: It also say says to format it as a released paper.
888: The fifth command says to use the same style (|cw[acm]),
889: but this time print the references as they
890: appear in |cw(bib) and
891: format the paper using |i(nroff).
892:
893:
894: |subsection(Command Line arguments)
895:
896: Command line arguments provide another way
897: to select bibliography databases and set style options.
898:
899: .ds l5 |cw(\-s) |i(sname)n
900: |begin(text_list)
901: |blank_space(1)
902: |item{"\f(CW\-p\fP \fIdbfile\fP"}specifies a bibliography
903: database, |i(dbfile) (default is |cw(prefer.out))
904: |blank_space(1)
905: |item{"\f(CW\-s\fP \fIsname\fP"}selects formatting style |i(sname)
906: (default is |cw(att)). The argument |i(sname)
907: names of one of the provided styles or
908: a user-defined style.
909: |blank_space(1)
910: |item{"\f(CW\-o\fP \fIokey\fP"}specifies how
911: the |cw<|sp(|s)reference_list>
912: command should order references.
913: The argument |i(okey) may be one of
914: |cw(sequence) (the default), |cw(sort), or a combination of
915: |cw(a), |cw(d), or |cw(t), as described above in Section
916: |remember(stylesec).
917: |blank_space(1)
918: |item{"\f(CW\-n\fP"}format using |i(nroff) rather than for |i(troff),
919: the default.
920: |blank_space(1)
921: |item{"\f(CW\-r\fP"}format as
922: a released paper, rather than an
923: internal technical memorandum, the default.
924: |end(text_list)
925: |blank_space(1)
926: |p
927: For example, the command
928:
929: |figure<|small[|cw{prefer -r -sacm -pmybib mydoc}]>
930:
931: processes |cw(mydoc) as a released paper, using |cw(acm) style
932: and the bibliography database |cw(mybib).
933:
934: |blank_space(1)
935: |section(Using |i<prefer> |b(With) |i<monk>)
936:
937: As mentioned earlier, the |i(monk) text formatting package
938: invokes |i(prefer) to format bibliographic references.
939: To do this, it must convert its own reference commands to ones
940: understood by |i(prefer).
941: For the
942: |cw<|sp(|s)reference>,
943: |cw<|sp(|s)reference_list>,
944: and |cw<|sp(|s)reference_database>
945: commands, this is easy;
946: |i(monk's) versions are identical to |i(prefer's).
947: Note that |i(monk) uses angle brackets |cw(<>)
948: to enclose the |i(prefer)
949: command arguments.
950: Thus if angle brackets appear in any of the command
951: arguments, confusion may arise.
952:
953: |p
954: The |cw<|sp(|s)reference_placement> command in |i(monk)
955: differs slightly from the |i(prefer) version, depending on
956: the |i(monk) document style.
957: For example, for technical memoranda
958: it causes a new page
959: to be printed and
960: the reference list to be headed by
961: a centered |small(|cw<REFERENCE>) title.
962:
963: |p
964: |i(Monk) does not have a
965: |cw<|sp(|s)reference_style> command.
966: Instead, it uses it's own |cw<|sp(|s)style> command
967: along with a |cw(reference) attribute/value pair.
968: For example, to change the reference style to |cw(ieee), use the
969: monk command
970:
971: |figure<|small[|sp(|s)style(reference ieee)]>
972:
973: To set any of the other options provided by the |i(prefer)
974: |cw<|sp(|s)reference_style> command,
975: use the |i(monk) |cw<|sp(|s)style> command
976: with a |cw(reference_option) attribute/value pair.
977: For example,
978:
979: |figure<|small[|sp(|s)style(reference_option rp)]>
980:
981: means format references for a released paper.
982: Other possible values for |cw(reference_option) are:
983: |cw(tm), |cw(troff), |cw(nroff), |cw(sort), |cw(sequence), and any
984: combination of the letters |cw(a), |cw(d), |cw(t).
985: These options have the same meanings as for
986: the |cw<|sp(|s)reference_style> command.
987: The command line options |cw<\-s>, |cw<\-o>, |cw<\-r>, and |cw<\-n>
988: of |i(prefer) are not set by |i(monk).
989: |i(Monk) uses the style command to set these options.
990:
991: |p
992: |i(Monk) uses the file |cw</usr/lib/monk/prefs> as its default bibliography
993: database.
994: You can specify an alternative database
995: with the |cw(\-R) option, which |i(monk) translates to the |cw<\-p>
996: option for |i(prefer).
997: For example,
998:
999: |figure<|small(|cw{monk \-Rmybib mydoc})>
1000:
1001: says that monk should use the file |cw(mybib)
1002: as the bibliography database when formatting |i(mydoc).
1003:
1004: |section(Converting From |i<refer> |b(To) |i<prefer> )
1005:
1006: The |i(pconvert) command converts a |i(refer) style bibliography
1007: database
1008: to |i(prefer) format.
1009: For example, the command
1010:
1011: |figure<|small(|cw{pconvert refer.out > prefer.out})>
1012:
1013: scans the file |cw(refer.out) and writes the transformed version
1014: into |cw(prefer.out).
1015: |i(Pconvert) uses the attributes of each
1016: entry to infer the |cw(%type) of the entry.
1017:
1018: |p
1019: With the |cw(\-d) option |i(pconvert)
1020: changes |i(refer) style commands in a document
1021: to |i(prefer) style.
1022: For example
1023:
1024: |figure<|small(|cw{pconvert \-d oldpaper > newpaper})>
1025:
1026: scans |cw(oldpaper) for |i(refer) citations
1027: and converts them to |i(prefer) commands,
1028: writing the output to |cw(newpaper).
1029:
1030:
1031: |section(Acknowledgements)
1032:
1033: Sharon Murrel and Ted Kowalski
1034: encouraged me to write |i(prefer) and then integrated
1035: it into |i(monk).
1036: The idea of using the |i(awk) language to format references
1037: came from Ravi Sethi.
1038: Julia Hirschberg, Joe Kruskal, and Ted Kowalski
1039: contributed style scripts.
1040: Thanks to those who offered feature suggestions
1041: bug reports, and
1042: comments on versions of
1043: this paper
1044: including
1045: Judy Friedman,
1046: Julia Hirschberg,
1047: Andrew Hume,
1048: Ted Kowalski,
1049: Joe Kruskal,
1050: Doug McIlroy,
1051: Mel Melchner,
1052: Marcel Meth,
1053: Sharon Murrel,
1054: John Puttress,
1055: Sande Pruzansky,
1056: Ravi Sethi,
1057: and
1058: Wayne Wolf.
1059:
1060: |reference_placement
1061:
1062: |comment<|new_page>
1063: .ne 3i
1064: |appendix(Bibliography Types And Attributes)
1065: |save(types)
1066:
1067: |insert(example/ptemplate.m)
1068:
1069: .ne 3i
1070: |appendix(Examples)
1071: |save(examples)
1072:
1073: This sample document contains many examples of
1074: |cw<|sp(|s)reference> commands followed by
1075: a |cw<|sp(|s)reference_placement>.
1076:
1077: |begin(here)
1078: |begin(figure)
1079: |begin(figsmall)
1080: |insert(example/type.in)
1081: |end(figsmall)
1082: |end(figure)
1083: |end(here)
1084:
1085: |p
1086: When |i(prefer) formats this document according to |cw(acm) style
1087: it looks like this:
1088:
1089: |p
1090: |begin(figsmall)
1091: |source(example/type.acm)
1092: |end(figsmall)
1093:
1094: |p
1095: When formatted according to |cw(apa) style
1096: it looks like this:
1097: |p
1098: |begin(figsmall)
1099: |source(example/type.apa)
1100: |end(figsmall)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.