Return to refer.bib CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 29.refer

Annotation of 43BSDReno/share/doc/usd/29.refer/refer.bib, revision 1.1

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.