![[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.