The Datafile PD-CD 4/DATAFILE_PDCD4.iso/unix/riscbsd/1_1_contri/usd/29_refer/refer_bib

Text File | 1986-06-02 | 29.1 KB | 828 lines

.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"    @(#)refer.bib    6.1 (Berkeley) 6/2/86
.\"
.EH 'USD:29-%''Refer \(em A Bibliography System'
.OH 'Refer \(em A Bibliography System''USD:29-%'
.if t .nr PD .5v
.nr LL 6.5i
.nr FL 6i
.    \" AP - abstract paragraph
.de AP
.sp \\n(PDu
.ti +\\n(PIu
..
.\".RP
.TL
Refer \(em A Bibliography System
.AU
Bill Tuthill
.AI
Computing Services
University of California
Berkeley, CA 94720
.AB
\fBRefer\fP is a bibliography system that supports data entry,
indexing, retrieval, sorting, runoff, convenient citations,
and footnote or endnote numbering.
This document assumes you know how to use some Unix editor,
and that you are familiar with the \fBnroff/troff\fP text formatters.
.AP
The \fBrefer\fP program is a preprocessor for \fBnroff/troff,\fP
like \fBeqn\fP and \fBtbl,\fP
except that it is used for literature citations,
rather than for equations and tables.
Given incomplete but sufficiently precise citations,
\fBrefer\fP finds references in a bibliographic database.
The complete references are formatted as footnotes,
numbered, and placed either at the bottom of the page,
or at the end of a chapter.
.AP
A number of ancillary programs make \fBrefer\fP easier to use.
The \fBaddbib\fP program is for creating and extending
the bibliographic database;
\fBsortbib\fP sorts the bibliography by author and date,
or other selected criteria;
and \fBroffbib\fP runs off the entire database,
formatting it not as footnotes,
but as a bibliography or annotated bibliography.
.AP
Once a full bibliography has been created,
access time can be improved by making an index
to the references with \fBindxbib\fP.
Then, the \fBlookbib\fP program can be used to quickly retrieve
individual citations or groups of citations.
Creating this inverted index will speed up \fBrefer,\fP
and \fBlookbib\fP will allow you to verify that a citation
is sufficiently precise to deliver just one reference.
.AE
.\"end cover
.SH
Introduction
.XS
Introduction
.XE
.PP
Taken together, the \fBrefer\fP programs constitute
a database system for use with variable-length information.
To distinguish various types of bibliographic material,
the system uses labels composed of upper case letters,
preceded by a percent sign and followed by a space.
For example, one document might be given this entry:
.DS
%A    Joel Kies
%T    Document Formatting on Unix Using the -ms Macros
%I    Computing Services
%C    Berkeley
%D    1980
.DE
Each line is called a field,
and lines grouped together are called a record;
records are separated from each other by a blank line.
Bibliographic information follows the labels,
containing data to be used by the \fBrefer\fP system.
The order of fields is not important,
except that authors should be entered
in the same order as they are listed on the document.
Fields can be as long as necessary,
and may even be continued on the following line(s).
.PP
The labels are meaningful to \fBnroff/troff\fP macros,
and, with a few exceptions,
the \fBrefer\fP program itself does not pay attention to them.
This implies that you can change the label codes,
if you also change the macros used by \fBnroff/troff\fP\|.
The macro package takes care of details like proper ordering,
underlining the book title or journal name,
and quoting the article's title.
Here are the labels used by \fBrefer,\fP
with an indication of what they represent:
.DS
%H    Header commentary, printed before reference
%A    Author's name
%Q    Corporate or foreign author (unreversed)
%T    Title of article or book
%S    Series title
%J    Journal containing article
%B    Book containing article
%R    Report, paper, or thesis (for unpublished material)
%V    Volume
%N    Number within volume
%E    Editor of book containing article
%P    Page number(s)
%I    Issuer (publisher)
%C    City where published
%D    Date of publication
%O    Other commentary, printed at end of reference
%K    Keywords used to locate reference
%L    Label used by \-k option of \fBrefer\fP
%X    Abstract (used by \fBroffbib,\fP not by \fBrefer\fP)
.DE
Only relevant fields should be supplied.
Except for %A, each field should be given only once;
in the case of multiple authors,
the senior author should come first.
The %Q is for organizational authors,
or authors with Japanese or Arabic names,
in which cases the order of names should be preserved.
Books should be labeled with the %T, not with the %B,
which is reserved for books containing articles.
The %J and %B fields should never appear together,
although if they do, the %J will override the %B.
If there is no author, just an editor,
it is best to type the editor in the %A field,
as in this example:
.DS
%A    Bertrand Bronson, ed.
.DE
The %E field is used for the editor of a book (%B)
containing an article, which has its own author.
For unpublished material such as theses, use the %R field;
the title in the %T field will be quoted,
but the contents of the %R field will not be underlined.
Unlike other fields, %H, %O, and %X should contain their own punctuation.
Here is a modest example:
.DS
%A    Mike E. Lesk
%T    Some Applications of Inverted Indexes on the Unix System
%B    Unix Programmer's Manual
%I    Bell Laboratories
%C    Murray Hill, NJ
%D    1978
%V    2a
%K    refer mkey inv hunt
%X    Difficult to read paper that dwells on indexing strategies,
giving little practical advice about using \efBrefer\efP.
.DE
Note that the author's name is given in normal order,
without inverting the surname;
inversion is done automatically,
except when %Q is used instead of %A.
We use %X rather than %O for the commentary
because we do not want the comment printed all the time.
The %O and %H fields are printed by both \fBrefer\fP and \fBroffbib;\fP
the %X field is printed only by \fBroffbib,\fP
as a detached annotation paragraph.
.SH
Data Entry with Addbib
.XS
Data Entry with Addbib
.XE
.PP
The \fBaddbib\fP program is for creating
and extending bibliographic databases.
You must give it the filename of your bibliography:
.DS
% \fBaddbib  database\fP
.DE
Every time you enter \fBaddbib\fP, it asks if you want instructions.
To get them, type \fBy\fP\|; to skip them, type \s-2RETURN\s0.
\fBAddbib\fP prompts for various fields, reads from the keyboard,
and writes records containing the \fBrefer\fP codes to the database.
After finishing a field entry,
you should end it by typing \s-2RETURN\s0.
If a field is too long to fit on a line,
type a backslash (\e) at the end of the line,
and you will be able to continue on the following line.
Note: the backslash works in this capacity only inside \fBaddbib\fP.
.PP
A field will not be written to the database
if nothing is entered into it.
Typing a minus sign as the first character of any field
will cause \fBaddbib\fP to back up one field at a time.
Backing up is the best way to add multiple authors,
and it really helps if you forget to add something important.
Fields not contained in the prompting skeleton may be entered
by typing a backslash as the last character before \s-2RETURN\s0.
The following line will be sent verbatim to the database
and \fBaddbib\fP will resume with the next field.
This is identical to the procedure for dealing with long fields,
but with new fields, don't forget the % key-letter.
.PP
Finally, you will be asked for an abstract (or annotation),
which will be preserved as the %X field.
Type in as many lines as you need, and end with a control-D
(hold down the \s-2CTRL\s0 button, then press the \*Qd\*U key).
This prompting for an abstract can be suppressed
with the \fB\-a\fP command line option.
.PP
After one bibliographic record has been completed,
\fBaddbib\fP will ask if you want to continue.
If you do, type \s-2RETURN\s0\|;
to quit, type \fBq\fP or \fBn\fP (quit or no).
It is also possible to use one of the system editors
to correct mistakes made while entering data.
After the \*QContinue?\*U prompt, type any of the following:
\fBedit, ex, vi,\fP or \fBed\fP \*-
you will be placed inside the corresponding editor,
and returned to \fBaddbib\fP afterwards,
from where you can either quit or add more data.
.PP
If the prompts normally supplied by \fBaddbib\fP are not enough,
are in the wrong order, or are too numerous,
you can redefine the skeleton by constructing a promptfile.
Create some file, to be named after the \-p command line option.
Place the prompts you want on the left side,
followed by a single \s-2TAB\s0 (control-I), then the \fBrefer\fP code
that is to appear in the bibliographic database.
\fBAddbib\fP will send the left side to the screen,
and the right side, along with data entered, to the database.
.SH
Printing the Bibliography
.XS
Printing the Bibliography
.XE
.PP
\fBSortbib\fP is for sorting the bibliography
by author (%A) and date (%D), or by data in other fields.
It is quite useful for producing bibliographies
and annotated bibliographies,
which are seldom entered in strict alphabetical order.
It takes as arguments the names of up to 16 bibliography files,
and sends the sorted records to standard output (the terminal screen),
which may be redirected through a pipe or into a file.
.PP
The \-s\fIKEYS\fP\| flag to \fBsortbib\fP will sort by fields
whose key-letters are in the \fIKEYS\fP\| string,
rather than merely by author and date.
Key-letters in \fIKEYS\fP\| may be followed by a `+'
to indicate that all such fields are to be used.
The default is to sort by senior author and date
(printing the senior author last name first),
but \-sA+D will sort by all authors and then date,
and \-sATD will sort on senior author, then title, and then date.
.PP
\fBRoffbib\fP is for running off the (probably sorted) bibliography.
It can handle annotated bibliographies \*-
annotations are entered in the %X (abstract) field.
\fBRoffbib\fP is a shell script that calls
\fBrefer\0\-B\fP and \fBnroff\0\-mbib\fP\|.
It uses the macro definitions that reside in /usr/lib/tmac/tmac.bib,
which you can redefine if you know \fBnroff\fP and \fBtroff\fP.
Note that \fBrefer\fP will print the %H and %O commentaries,
but will ignore abstracts in the %X field;
\fBroffbib\fP will print both fields,
unless annotations are suppressed with the \-x option.
.PP
The following command sequence will lineprint the entire bibliography,
organized alphabetically by author and date:
.DS
% \fBsortbib  database  |  roffbib  |  lpr\fP
.DE
This is a good way to proofread the bibliography,
or to produce a stand-alone bibliography at the end of a paper.
Incidentally, \fBroffbib\fP accepts all flags used with \fBnroff\fP.
For example:
.DS
% \fBsortbib  database  |  roffbib  \-Tdtc  \-s1\fP
.DE
will make accent marks work on a DTC daisy-wheel printer,
and stop at the bottom of every page for changing paper.
The \-n and \-o flags may also be quite useful,
to start page numbering at a selected point,
or to produce only specific pages.
.PP
\fBRoffbib\fP understands four command-line number registers,
which are something like the two-letter number registers in \-ms.
The \-rN1 argument will number references beginning at one (1);
use another number to start somewhere besides one.
The \-rV2 flag will double-space the entire bibliography,
while \-rV1 will double-space the references,
but single-space the annotation paragraphs.
Finally, specifying \-rL6i changes the line length
from 6.5 inches to 6 inches,
and saying \-rO1i sets the page offset
to one inch, instead of zero.
(That's a capital O after \-r, not a zero.)
.SH
Citing Papers with Refer
.XS
Citing Papers with Refer
.XE
.PP
The \fBrefer\fP program normally copies input to output,
except when it encounters an item of the form:
.DS
\&.[
partial  citation
\&.]
.DE
The partial citation may be just an author's name and a date,
or perhaps a title and a keyword, or maybe just a document number.
\fBRefer\fP looks up the citation in the bibliographic database,
and transforms it into a full, properly formatted reference.
If the partial citation does not correctly identify a single work
(either finding nothing, or more than one reference),
a diagnostic message is given.
If nothing is found, it will say \*QNo such paper.\*U
If more than one reference is found,
it will say \*QToo many hits.\*U
Other diagnostic messages can be quite cryptic;
if you are in doubt, use \fBchecknr\fP to verify
that all your .['s have matching .]'s.
.PP
When everything goes well,
the reference will be brought in from the database,
numbered, and placed at the bottom of the page.
This citation,
.[
lesk inverted indexes
.]
for example, was produced by:
.DS
This citation,
\&.[
lesk  inverted  indexes
\&.]
for example, was produced by
.DE
The .[ and .] markers, in essence,
replace the .FS and .FE of the \-ms macros,
and also provide a numbering mechanism.
Footnote numbers will be bracketed on the the lineprinter,
but superscripted on daisy-wheel terminals and in \fBtroff\fP\|.
In the reference itself, articles will be quoted,
and books and journals will be underlined in \fBnroff,\fP
and italicized in \fBtroff.\fP
.PP
Sometimes you need to cite a specific page number
along with more general bibliographic material.
You may have, for instance,
a single document that you refer to several times,
each time giving a different page citation.
This is how you could get \*Qp.\010\*U in the reference:
.DS
\&.[
kies  document  formatting
%P    10
\&.]
.DE
The first line, a partial citation,
will find the reference in your bibliography.
The second line will insert the page number into the final citation.
Ranges of pages may be specified as \*Q%P\056-78\*U.
.PP
When the time comes to run off a paper,
you will need to have two files:
the bibliographic database, and the paper to format.
Use a command line something like one of these:
.DS
% \fBrefer  \-p  database  paper | nroff  \-ms\fP
% \fBrefer  \-p  database  paper | tbl | nroff  \-ms\fP
% \fBrefer  \-p  database  paper | tbl | neqn | nroff  \-ms\fP
.DE
If other preprocessors are used,
\fBrefer\fP should precede \fBtbl,\fP
which must in turn precede \fBeqn\fP or \fBneqn\fP\|.
The \-p option specifies a \*Qprivate\*U database,
which most bibliographies are.
.SH
Refer's Command-line Options
.XS
Refer's Command-line Options
.XE
.PP
Many people like to place references at the end of a chapter,
rather than at the bottom of the page.
The \-e option will accumulate references
until a macro sequence of the form
.DS
\&.[
$LIST$
\&.]
.DE
is encountered (or until the end of file).
\fBRefer\fP will then write out all references collected
up to that point, collapsing identical references.
Warning: there is a limit (currently 200)
on the number of references that can be accumulated at one time.
.PP
It is also possible to sort references that appear at the end of text.
The \-s\fIKEYS\fP flag will sort references by fields
whose key-letters are in the \fIKEYS\fP string,
and permute reference numbers in the text accordingly.
It is unnecessary to use \-e with it, since \-s implies \-e.
Key-letters in \fIKEYS\fP may be followed by a `+'
to indicate that all such fields are to be used.
The default is to sort by senior author and date,
but \-sA+D will sort on all authors and then date,
and \-sA+T will sort by authors and then title.
.PP
\fBRefer\fP can also make citations in what is known as
the Social or Natural Sciences format.
Instead of numbering references, the \-l (letter ell) flag makes labels
from the senior author's last name and the year of publication.
For example, a reference to the paper on Inverted Indexes
cited above might appear as [Lesk1978a].
It is possible to control the number of characters in the last name,
and the number of digits in the date.
For instance, the command line argument \-l6,2 might
produce a reference such as [Kernig78c].
.PP
Some bibliography standards shun both footnote numbers
and labels composed of author and date,
requiring some keyword to identify the reference.
The \-k flag indicates that, instead of numbering references,
key labels specified on the %L line should be used to mark references.
.PP
The \-n flag means to not search the default reference file,
located in /usr/dict/papers/Rv7man.
Using this flag may make \fBrefer\fP marginally faster.
The \-a\fIn\fP flag will reverse the first \fIn\fP author names,
printing Jones, J. A. instead of J. A. Jones.
Often \-a1 is enough; this will reverse the names of only the senior author.
In some versions of \fBrefer\fP there is also the \-f flag
to set the footnote number to some predetermined value;
for example, \-f23 would start numbering with footnote 23.
.SH
Making an Index
.XS
Making an Index
.XE
.PP
Once your database is large and relatively stable,
it is a good idea to make an index to it,
so that references can be found quickly and efficiently.
The \fBindxbib\fP program makes an inverted index
to the bibliographic database
(this program is called \fBpubindex\fP in the Bell Labs manual).
An inverted index could be compared to
the thumb cuts of a dictionary \*-
instead of going all the way through your bibliography,
programs can move to the exact location where a citation is found.
.PP
\fBIndxbib\fP itself takes a while to run,
and you will need sufficient disk space to store the indexes.
But once it has been run, access time will improve dramatically.
Furthermore, large databases of several million characters
can be indexed with no problem.
The program is exceedingly simple to use:
.DS
% \fBindxbib  database\fP
.DE
Be aware that changing your database will require
that you run \fBindxbib\fP over again.
If you don't, you may fail to find a reference
that really is in the database.
.PP
Once you have built an inverted index,
you can use \fBlookbib\fP to find references in the database.
\fBLookbib\fP cannot be used until you have run \fBindxbib\fP\|.
When editing a paper, \fBlookbib\fP is very useful
to make sure that a citation can be found as specified.
It takes one argument, the name of the bibliography,
and then reads partial citations from the terminal,
returning references that match, or nothing if none match.
Its prompt is the greater-than sign.
.DS
% \fBlookbib  database\fP
> \fBlesk inverted indexes\fP
%A    Mike E. Lesk
%T    Some Applications of Inverted Indexes on the Unix System
%J    Unix Programmer's Manual
%I    Bell Laboratories
%C    Murray Hill, NJ
%D    1978
%V    2a
%X    Difficult to read paper that dwells on indexing strategies,
giving little practical advice about using \efBrefer\efP.
>
.DE
If more than one reference comes back,
you will have to give a more precise citation for \fBrefer\fP\|.
Experiment until you find something that works;
remember that it is harmless to overspecify.
To get out of the \fBlookbib\fP program,
type a control-D alone on a line;
\fBlookbib\fP then exits with an ``EOT'' message.
.PP
\fBLookbib\fP can also be used to extract groups of related citations.
For example, to find all the papers by Brian Kernighan
found in the system database, and send the output to a file, type:
.DS
% \fBlookbib  /usr/dict/papers/Ind  >  kern.refs\fP
> \fBkernighan\fP
> EOT
% \fBcat  kern.refs\fP
.DE
Your file, \*Qkern.refs\*U, will be full of references.
A similar procedure can be used
to pull out all papers of some date,
all papers from a given journal,
all papers containing a certain group of keywords, etc.
.SH
Refer Bugs and Some Solutions
.XS
Refer Bugs and Some Solutions
.XE
.PP
The \fBrefer\fP program will mess up if there are blanks
at the end of lines, especially the %A author line.
\fBAddbib\fP carefully removes trailing blanks,
but they may creep in again during editing.
Use an editor command \*-
.if n g/  *$/s///  \*-
.if t g/\0\0\(**$/s///  \*-
to remove trailing blanks from your bibliography.
.PP
Having bibliographic fields passed through as string definitions
implies that interpolated strings (such as accent marks)
must have two backslashes, so they can pass through copy mode intact.
For instance, the word \*Qt\o'e\(aa'l\o'e\(aa'phone\*U
would have to be represented:
.DS
te\e\e\(**\'le\e\e\(**\'phone
.DE
in order to come out correctly.
In the %X field, by contrast,
you will have to use single backslashes instead.
This is because the %X field is not passed through as a string,
but as the body of a paragraph macro.
.PP
Another problem arises from authors with foreign names.
When a name like \*QVal\o"e\(aa"ry Giscard d'Estaing\*U
is turned around by the \-a option of \fBrefer,\fP
it will appear as \*Qd'Estaing, Val\o"e\(aa"ry Giscard,\*U
rather than as \*QGiscard d'Estaing, Val\o"e\(aa"ry.\*U
To prevent this, enter names as follows:
.DS
%A    Vale\e\e\(**\'ry   Giscard\e0d'Estaing
%A    Alexander   Csoma\e0de\e0Ko\e\e\(**:ro\e\e\(**:s
.DE
(The second is the name of a famous Hungarian linguist.)
The backslash-zero is an \fBnroff/troff\fP request
meaning to insert a digit-width space.
It will protect against faulty name reversal,
and also against mis-sorting.
.PP
Footnote numbers are placed at the end of the line before the .[ macro.
This line should be a line of text, not a macro.
As an example, if the line before the .[ is a .R macro,
then the .R will eat the footnote number.
(The .R is an \-ms request meaning change to Roman font.)
In cases where the font needs changing,
it is necessary to do the following:
.DS
\efIet al.\efR
\&.[
awk  aho  kernighan  weinberger
\&.]
.DE
Now the reference will be to Aho \fIet al\fR.
.[
awk aho kernighan
.]
The \efI changes to italics, and the \efR changes back to Roman font.
Both these requests are \fBnroff/troff\fP requests, not part of \-ms.
If and when a footnote number is added after this sequence,
it will indeed appear in the output.
.SH
Internal Details of Refer
.XS
Internal Details of Refer
.XE
.PP
You have already read everything you need to know
in order to use the \fBrefer\fP bibliography system.
The remaining sections are provided only for extra information,
and in case you need to change the way \fBrefer\fP works.
.PP
The output of \fBrefer\fP is a stream of string definitions,
one for each field in a reference.
To create string names,
percent signs are simply changed to an open bracket,
and an [F string is added, containing the footnote number.
The %X, %Y and %Z fields are ignored;
however, the \fBannobib\fP program changes the %X
to an .AP (annotation paragraph) macro.
The citation used above yields this intermediate output:
.DS
.ta \w'.ds\0'u +\w'[D\0'u
\&.ds    [F    1
\&.]-
\&.ds    [A    Mike E. Lesk
\&.ds    [T    Some Applications of Inverted Indexes on the Unix System
\&.ds    [J    Unix Programmer's Manual
\&.ds    [I    Bell Laboratories
\&.ds    [C    Murray Hill, NJ
\&.ds    [D    1978
\&.ds    [V    2a
\&.nr    [T    0
\&.nr    [A    0
\&.nr    [O    0
\&.][  1  journal-article
.DE
These string definitions are sent to \fBnroff\fP,
which can use the \-ms macros defined in /usr/lib/mx/tmac.xref
to take care of formatting things properly.
The initializing macro \fB.]\-\fP precedes the string definitions,
and the labeled macro \fB.][\fP follows.
These are changed from the input \fB.[\fP and \fB.]\fP so that
running a file twice through \fBrefer\fP is harmless.
.PP
The \fB.][\fP macro, used to print the reference,
is given a type-number argument, which is a numeric label
indicating the type of reference involved.
Here is a list of the various kinds of references:
.DS
.ta \w'Field\0\0\0'u +\w'Value\0\0'u
Field    Value    Kind of Reference
\l'\w'Field\0\0\0Value\0\0Kind of Reference\0'u'
%J     1    Journal Article
%B     3    Article in Book
%R %G     4    Report, Government Report
%I     2    Book
%M     5    Bell Labs Memorandum (undefined)
none     0    Other
.DE
The order listed above is indicative of the precedence
of the various fields.
In other words, a reference that has both the %J and %B fields
will be classified as a journal article.
If none of the fields listed is present,
then the reference will be classified as \*Qother.\*U
.PP
The footnote number is flagged in the text with the following sequence,
where \fInumber\fP is the footnote number:
.DS
\e*([.\fInumber\fP\e*(.]
.DE
The \e*([. and \e*(.] stand for bracketing or superscripting.
In \fBnroff\fP with low-resolution devices such as the lpr and a crt,
footnote numbers will be bracketed.
In \fBtroff,\fP or on daisy-wheel printers,
footnote numbers will be superscripted.
Punctuation normally comes before the reference number;
this can be changed by using the \-P (postpunctuation)
option of \fBrefer\fP.
.PP
In some cases, it is necessary to override
certain fields in a reference.
For instance, each time a work is cited,
you may want to specify different page numbers,
and you may want to change certain fields.
This citation will find the Lesk reference,
but will add specific page numbers to the output,
even though no page numbers appeared in the original reference.
.DS
\&.[
lesk  inverted  indexes
%P    7-13
%I    Computing Services
%O    UNX 12.2.2.
\&.]
.DE
The %I line will also override any previous publisher information,
and the %O line will append some commentary.
The \fBrefer\fP program simply adds
the new %P, %I, and %O strings to the output,
and later strings definitions cancel earlier ones.
.PP
It is also possible to insert an entire citation
that does not appear in the bibliographic database.
This reference, for example, could be added as follows:
.DS
\&.[
%A    Brian Kernighan
%T    A Troff Tutorial
%I    Bell Laboratories
%D    1978
\&.]
.DE
This will cause \fBrefer\fP to interpret the fields exactly as given,
without searching the bibliographic database.
This practice is not recommended, however, because it's better
to add new references to the database, so they can be used again later.
.PP
If you want to change the way footnote numbers are printed,
signals can be given on the \fB.[\fP and \fB.]\fP lines.
For example, to say \*QSee reference (2),\*U
the citation should appear as:
.DS
See reference
\&.[(
partial citation
\&.]),
.DE
Note that blanks are significant on these signal lines.
If a permanent change in the footnote format is desired,
it's best to redefine the \fB[.\fP and \fB.]\fP strings.
.SH
Changing the Refer Macros
.XS
Changing the Refer Macros
.XE
.PP
This section is provided for those who wish to rewrite
or modify the \fBrefer\fP macros.
This is necessary in order to make output correspond
to specific journal requirements, or departmental standards.
First there is an explanation of how new macros
can be substituted for the old ones.
Then several alterations are given as examples.
Finally, there is an annotated copy of
the \fBrefer\fP macros used by \fBroffbib\fP\|.
.PP
The \fBrefer\fP macros for \fBnroff/troff\fP supplied by
the \-ms macro package reside in /usr/lib/mx/tmac.xref;
they are reference macros, for producing footnotes or endnotes.
The \fBrefer\fP macros used by \fBroffbib,\fP
on the other hand, reside in /usr/lib/tmac/tmac.bib;
they are for producing a stand-alone bibliography.
.PP
To change the macros used by \fBroffbib,\fP
you will need to get your own version of this shell script
into the directory where you are working.
These two commands will get you a copy of \fBroffbib\fP
and the macros it uses: \(dg
.DS
% \fBcp  /usr/lib/tmac/tmac.bib  bibmac\fP
.DE
You can proceed to change bibmac as much as you like.
Then when you use \fBroffbib\fP,
you should specify your own version of the macros,
which will be substituted for the normal ones
.DS
% \fBroffbib  \-m  bibmac\fR  \fIfilename\fP
.DE
where \fIfilename\fP is the name of your bibliography file.
Make sure there's a space between \-m and \fBbibmac\fP.
.PP
If you want to modify the \fBrefer\fP macros
for use with \fBnroff\fP and the \-ms macros,
you will need to get a copy of \*Qtmac.xref\*U:
.DS
% \fBcp  /usr/lib/ms/s.ref  refmac\fP
.DE
These macros are much like \*Qbibmac\*U,
except they have .FS and .FE requests,
to be used in conjunction with the \-ms macros,
rather than independently defined .XP and .AP requests.
Now you can put this line at the top of the paper to be formatted:
.DS
\&.so  refmac
.DE
Your new \fBrefer\fP macros will override the definitions
previously read in by the \-ms package.
This method works only if \*Qrefmac\*U is in the working directory.
.PP
Suppose you didn't like the way dates are printed,
and wanted them to be parenthesized, with no comma before.
There are five identical lines you will have to change.
The first line below is the old way,
while the second is the new way:
.DS
\&.if  !"\e\e*([D""  ,  \e\e*([D\ec
\&.if  !"\e\e*([D""  \e&  (\e\e*([D)\ec
.DE
In the first line, there is a comma and a space, but no parentheses.
The \*Q\ec\*U at the end of each line
indicates to \fBnroff\fP that it should continue,
leaving no extra space in the output.
The \*Q\e&\*U in the second line is the do-nothing character;
when followed by a space, a space is sent to the output.
.PP
If you need to format a reference in the style
favored by the Modern Language Association
or Chicago University Press,
in the form (city: publisher, date),
then you will have to change the middle of
the book macro [2 as follows:
.DS
\e&  (\ec
\&.if  !"\e\e*([C""  \e\e*([C:
\e\e*([I\ec
\&.if  !"\e\e*([D""  ,  \e\e*([D\ec
)\ec
.DE
This would print (Berkeley: Computing Services, 1982)
if all three strings were present.
The first line prints a space and a parenthesis;
the second prints the city (and a colon) if present;
the third always prints the publisher
(books must have a publisher, or else they're classified as other);
the fourth line prints a comma and the date if present;
and the fifth line closes the parentheses.
You would need to make similar changes to the other macros as well.
.SH
Acknowledgements
.XS
Acknowledgements
.XE
.PP
Mike Lesk of Bell Laboratories wrote the original \fBrefer\fP software,
including the indexing programs.
Al Stangenberger of the Forestry Department
wrote the first version of \fBaddbib\fP, then called \fBbibin\fP.
Greg Shenaut of the Linguistics Department
wrote the original versions of \fBsortbib\fP and \fBroffbib\fP.
All these contributions are greatly appreciated.
.nr Pg \n(PN+1
.XS \n(Pg
Commented Refer Macros
.XE
.nr LL 6i
.TC