refer

unix v7是最后一个广泛发布的研究型UNIX版本

citation, a field is available which is searched but not
printed (\f3K\f1).
.PP
The key letters currently recognized by
.I refer
and
.I \-ms,
with the kind of information implied, are:
.KS
.TS
center;
c c6 c c
c l c l.
Key	Information specified	Key	Information specified
A	Author's name	N	Issue number
B	Title of book containing item	O	Other information
C	City of publication	P	Page(s) of article
D	Date	R	Technical report reference
E	Editor of book containing item	T	Title
G	Government (NTIS) ordering number	V	Volume number
I	Issuer (publisher)
J	Journal name
K	Keys (for searching)	X	or
L	Label	Y	or
M	Memorandum label	Z	Information not used by \f2refer\f1
.TE
.KE
For example, a sample reference could be
typed as:
.DS
%T Bounds on the Complexity of the Maximal
Common Subsequence Problem
%Z ctr127
%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ullman
%J J. ACM
%V 23
%N 1
%P 1-12
.\"%M TM 75-1271-7
%M abcd-78
%D Jan. 1976
.DE
Order is irrelevant, except that authors are shown in the order
given.  The output of
.I refer
is a stream of string definitions, one
for each of the fields of each reference, as
shown below.
.DS
\*.]-
\*.ds [A authors' names \*.\*.\*.
\*.ds [T title \*.\*.\*.
\*.ds [J journal \*.\*.\*.
\*.\*.\*.
\*.]\|[ type-number
.DE
The
.I refer
program, in general, does not concern itself with the significance
of the strings.
The different fields are treated identically by
.I refer ,
except that the
X, Y and Z fields are ignored (see the
.B \-i
option of
.I mkey\^ )
in indexing and searching.
All
.I refer
does is select the appropriate citation, based on the keys.
The macro package must arrange the strings so as to produce an appropriately
formatted citation.
In this process, it uses the convention that the `T' field is the title,
the `J' field the journal, and so forth.
.PP
The
.I refer
program does arrange the citation to simplify the macro package's
job, however.
The special macro
.B \&\*.]\-
precedes the string definitions
and the special macro
.B \*.]\|[
follows.
These are changed from the input
.B \*.[
and 
.B \*.\^]
so that running the same file through
.I refer
again is harmless.
The 
.B \*.]\-
macro can be used by the macro package to
initialize.
The 
.B \*.]\|[
macro, which should be used
to print the reference, is given an
argument
.I type-number
to indicate the kind of reference, as follows:
.KS
.TS
center;
c c
n l.
Value	Kind of reference
1	Journal article
2	Book
3	Article within book
4	Technical report
5	Bell Labs technical memorandum
0	Other
.TE
.KE
The type is determined by the presence or absence of particular fields
in the citation (a journal article must have a `J' field, a book must have
an `I' field, and so forth).
To a small extent, this violates
the above rule that
.I refer
does not concern itself with the contents of the citation;
however, the classification of the citation in
.I troff
macros would require a relatively expensive and obscure
program.
Any macro writer may, of course, preserve consistency by ignoring
the argument to the
.B \*.]\|[
macro.
.PP
The reference is flagged in the text
with the sequence
.DS
\e*\|([\*.number\e*\|(\*.\^]
.DE
where
.I number
is the footnote number.
The strings
.B [\*.
and 
.B \*.\^]
should be used by the macro package
to format the reference flag in the text.
These strings can be replaced for a particular
footnote, as described in section 5.
The footnote number (or other signal) is available
to the reference macro
.B \*.]\|[
as the
string register
.B [F .
To simplify dealing with a text reference that occurs
at the end of a sentence,
.I refer
treats a reference which follows a period in a special way.
The period is removed, and the reference is preceded by
a call for the string
.B <.
and followed by a call for the string
.B >.
For example, if a reference follows ``end.'' it will appear
as
.DS
end\e*(<\*.\e*([\*.number\e*(\*.]\e*(>\*.
.DE
where
.I number
is the footnote number.
The macro package should turn either the string
.B >.
or
.B <.
into a period and delete the other one.
This permits the output to have either the form
``end[31].'' or ``end.\s-3\u31\d\s0'' as the
macro package wishes.
Note that in one case the period precedes the number and in the
other it follows the number.
.PP
In some cases users wish to suspend the searching, and merely
use the reference macro formatting.
That is, the user doesn't want to provide a search key
between
.B \*.[
and 
.B \*.\^]
brackets, but merely
the reference lines for the appropriate document.
Alternatively, the user
can wish
to add a few fields to those in the reference
as in the standard file, or
override some fields.
Altering or replacing fields, or supplying whole references, is easily done
by inserting lines beginning
with
.B % ;
any such line is taken as
direct input to the reference
processor rather than keys to be searched.
Thus
.DS
\*.[
key1 key2 key3 \*.\*.\*.
%Q New format item
%R Override report name
\*.\^]
.DE
makes the indicates changes to the result of searching for
the keys.
All of the search keys must be given before the first
\f3%\f1 line.
.PP
If no search keys are provided, an entire citation can
be provided in-line in the text.
For example, if the
.I eqn
paper citation were to be inserted in
this way, rather than by searching for it in the data base,
the input would read
.DS
\&\*.\*.\*.
\&preprocessor like
\&.I eqn.
\&.[
\&%A B. W. Kernighan
\&%A L. L. Cherry
\&%T A System for Typesetting Mathematics
\&%J Comm. ACM
\&%V 18
\&%N 3
\&%P 151-157
\&%D March 1975
\&.]
\&It scans its input looking for items
\&\*.\*.\*.
.DE
This would produce a citation of the same appearance as that
resulting from the file search.
.PP
As shown, fields are normally turned into
.I troff
strings.
Sometimes users would rather have them defined as macros,
so that other
.I troff
commands can be placed into the data.
When this is necessary, simply double the control character
.B %
in the data.
Thus the input
.DS
\&.[
%V 23
%%M
Bell Laboratories,
Murray Hill, N.J. 07974
\&.]
.DE
is processed by
.I refer
into
.DS
\&.ds [V 23
\&.de [M
Bell Laboratories,
Murray Hill, N.J. 07974
\&..
.DE
The information after
.B %%M
is defined as a macro to be invoked by
.B .[M
while the information after
.B %V
is turned into a string to be invoked by
.B \e\(**([V .
At present
.I \-ms
expects all information as strings.
.NH
Collecting References and other Refer Options
.PP
Normally, the combination of
.I refer
and
.I \-ms
formats output as 
.I troff
footnotes which are consecutively numbered and placed
at the bottom of the page.  However,
options exist to
place the references at the end; to arrange references alphabetically
by senior author; and to indicate references by strings in the text of the form
[Name1975a]
rather than by number.
Whenever references are not placed at the bottom of a page
identical references are coalesced.
.PP
For example, the
.B \-e
option to
.I refer
specifies that references are to be collected; in this case
they are output whenever the sequence
.DS
\*.[
$LIST$
\*.\^]
.DE
is encountered.
Thus, to place references at the end of a paper, the user would run
.I refer
with the
.I \-e
option and place the above $LIST$ commands after the last
line of the text.
.I Refer
will then move all the references to that point.
To aid in formatting the collected references,
.I refer
writes the references preceded by the line
.DS
.B .]<
.DE
and
followed by the line
.DS
.B .]>
.DE
to invoke special macros before and after the references.
.PP
Another possible option to
.I refer
is the
.B \-s
option to specify
sorting of references.  The default,
of course, is to list references in the order presented.
The
.B \-s
option implies the
.B \-e
option, and thus requires
a
.DS
\*.[
$LIST$
\*.\^]
.DE
entry to call out the reference list.
The
.B \-s
option may be followed by a string of letters, numbers, and `+' signs indicating how
the references are to be sorted.
The sort is done using the fields whose key-letters are
in the string as sorting keys; the numbers indicate how many
of the fields are to be considered, with `+'
taken as a large number.
Thus the default is
.B \-sAD
meaning ``Sort on senior author, then date.''  To
sort on all authors and then title, specify
.B \-sA+T .
And to sort on two authors and then the journal,
write
.B \-sA2J .
.PP
Other options to
.I refer
change the signal or label inserted in the text for each reference.
Normally these are just sequential numbers,
and their exact placement (within brackets, as superscripts, etc.) is determined
by the macro package.
The
.B \-l
option replaces reference numbers by
strings composed of the senior author's last name, the date,
and a disambiguating letter.
If a number follows the
.B l
as in
.B \-l3
only that many letters of the last name are used
in the label string.
To abbreviate the date as well the form
\f3-l\f2m,n\f1
shortens the last name to the
first
.I m
letters and the date to the
last
.I n
digits.
For example, the option
.B \-l3,2
would refer to the
.I eqn
paper (reference 3) by the signal
.I Ker75a ,
since it is the first cited reference by Kernighan in 1975.
.PP
A user wishing to specify particular labels for
a private bibliography may use the
.B \-k
option.
Specifying
\f3\-k\f2x\f1
causes the field \f2x\f1 to be used as a label.
The default is \f3L\f1.
If this field ends in \f3\-\f1, that character
is replaced by a sequence letter; otherwise the field
is used exactly as given.
.PP
If none of the
.I refer -produced
signals are desired,
the
.B \-b
option entirely suppresses automatic text signals.
.PP
If the user wishes to override the
.I \-ms
treatment of the reference signal (which is normally to
enclose the number in brackets in
.I nroff
and make it a superscript in
.I troff\\| )
this can be done easily.
If the lines
.B \&.[
or
.B \&.]
contain anything following these characters,
the remainders of these lines are used to surround
the reference signal, instead of the default.
Thus, for example, to say ``See reference (2).''
and avoid
``See reference.\s-3\u2\d\s+3'' the
input might appear
.DS
\&See reference
\&\*.[ (
imprecise citation ...
\&\*.\^])\*.
.DE
Note that blanks are significant in this construction.
If a permanent change is desired in the style of reference
signals, however, it is probably easier to redefine the strings
.B \&[.
and
.B \&.]
(which are used to bracket each signal)
than to change each citation.
.PP
Although normally
.I refer
limits itself to retrieving the data for the reference,
and leaves to a macro package the job of arranging that
data as required by the local format, there are two
special options for rearrangements that can not be
done by macro packages.
The
.B \-c
option puts fields into all upper case
(C\s-2APS\s+2-S\s-2MALL\s+2 C\s-2APS\s+2
in
.I troff
output).
The key-letters indicated what information is to be translated
to upper case follow the
.B c ,
so that
.B \-cAJ
means that authors' names and journals are to be in caps.
The
.B \-a
option writes the names of authors last name first, that is
.I "A. D. Hall, Jr."
is written as
.I "Hall, A. D. Jr" .
The citation form of
the
.I "Journal of the ACM" ,
for example, would require
both
.B \-cA
and
.B \-a
options.
This produces authors' names in the style
.I
K\s-2ERNIGHAN\s0, B. W. \s-2AND\s0 C\s-2HERRY\s0, L. L.\&
.R
for the previous example.
The
.B \-a
option may be followed by a number to indicate how many
author names should be reversed;
.B \-a1
(without any
.B \-c
option)
would produce
.I
Kernighan, B. W. and L. L. Cherry,
.R
for example.
.PP
Finally, there is also the previously-mentioned
.B \-p
option to let the user specify
a private file of references to be searched before the public files.
Note that
.I refer
does not insist on a previously made index for these files.
If a file is named which contains reference
data but is not indexed, it will be searched
(more slowly)
by
.I refer
using
.I fgrep.
In this way
it is easy for users to keep small files of
new references, which can later be added to the
public data bases.
.SG MH-1274-MEL-\s8UNIX\s0