bibdoc.ms

早期freebsd实现

The A command controls how authors' names are to be formatted.  It can be
followed by the following character sequences:
.RS
.IP A 6m
Authors' names are to be abbreviated
(see the section \fBAbbreviations\fP, below).
.IP R\fInum\fP
The first \fInum\fP authors' names are to be reversed.  If \fInum\fP is
omitted, all authors' names are reversed.
.IP X
Authors' names are to be printed in Caps-Small Caps style.
.RE
.IP E
The E command is equivalent to the A command, except that it controls the
formatting of editors' names.
.IP F
The F command indicates that references are to be dumped immediately after
a line containing a citation, such as when the references are to be placed
in footnotes.
.IP "S \fItemplate\fP"
The S command indicates references are to be sorted before being dumped.
The comparison used in sorting is based on the \fItemplate\fP.  See
the discussion in the section \fBSort Template\fP for an explanation of 
templates.
.IP "C \fItemplate\fP"
The \fItemplate\fP is used as a model in constructing citations.
See the discussion below in the section \fBCitation Templates\fP.
.IP "D \fI\0word \0definition\fP"
The word-definition pair is placed into a table.
Before each reference is dumped it is examined for the
occurrence of these words.  Any occurrence of a word from this table is replaced
by the definition, which is then rescanned for other words.
Words are limited to alphanumeric characters, ampersand and underscore.
Definitions can extend over multiple lines by ending lines with a backslash
(\e).  The backslash will be removed, and the definition, including the newline
and the next line,
will be entered into the table.  This is useful for including several
fields as part of a single definition (city names can be included as part
of a definition for a publishing house, for example).
.IP
\fIBib\fP has been enhanced to recognize macro calls where the macro name is 
surrounded by vertical \(brbars\(br.  This enhancement was implemented to
to provide a little more compatibility between \fIbib\fP and Tib,
a preprocessor that uses a database format very similar to \fIbib\fP's.
To have \fIbib\fP recognize only macro names surrounded by vertical
bars, invoke the \-Tib option.
.IP "I \fIfilename\fP"
The indicated file is included at the current point.  The included file may
contain other formatting commands.
.IP H
Three or more contiguous citations that refer to adjacent items in the
reference list are replaced by a hyphenated string.  For example, the
citation 2,3,4,5 would be replaced by 2-5.  This is most useful with
numeric citations.  The H option implies the O option.
.IP O
Contiguous citations are sorted according to the order given by the reference
list.
.IP "R \fInumber\fP"
The first \fInumber\fP author's names are reversed on output (i.e. T. A. Budd
becomes Budd, T. A.).
If number is omitted all names are reversed.
.IP "T \fIstr\fP"
The \fIstr\fP is a list of field names.  Each time a definition string for
a named field is produced, a second string containing just the last character
will also be generated.  See the section \fBTrailing Characters\fP below.
.IP X
Authors' last names are to be printed in Caps/Small Caps
format (i.e., Budd becomes B\s-2UDD\s+2).
.PP
\fB ** NOTE ** 
The first line encountered in the format input that does not match 
a format command
causes that line, and all subsequent lines, to be immediately copied to
the output without further processing.\fP
.SH
File Naming Conventions
.PP
Standard database format files are kept in a standard library area.
The string BMACLIB in bib.h points to this directory (/usr/new/lib/bmac in
the distribution).  In addition, this name is always defined when
reading format files, and is defined with the l] macro when processing
with \fItroff\fP.
The first command output by \fIbib\fP defines the string l] to be this
standard macro database directory.  This allows macro files to be
independent of where they are actually stored.
There are three types of files:
.IP bib.xxx 10m
These files contain bib commands to format documents in the xxx style.
.IP bmac.xxx
These files are the \fItroff\fP macros to actually implement a style.
They are generally not examined by \fIbib\fP at all, but are processed
by troff in response to a .so command.
.IP bibinc.xxx
These files contain information (such as definitions) used by more than one
style database.  The two usual files are bibinc.fullnames and 
bibinc.shortnames.  Both of these include files bibinc.Xlocal (where X
is full or short, respectively).  Due to the way \fIbib\fP searches for
files, if the user has these in his local directory, they will be read
just before the contents of bibinc.Xnames are processed.
.SH
Troff Naming Conventions
.PP
There is a simple naming convention for strings, registers and macros used
by \fIbib\fP during processing by \fItrof\fP.  
All strings, registers and macros are denoted by two character
names containing either a left or right brace.  The following are general rules:
.IP [\fIx\fP
If \fIx\fP is alphanumeric, the string contains the value of a reference field.
If \fIx\fP is nonalphanumeric, this is a formatting string preceding a citation.
.IP ]\fIx\fP
If \fIx\fP is alphanumeric, this is the final character from a reference field.
If \fIx\fP is nonalphanumeric, the string is formatting information within a citation.
.IP \fIx\fP[
Strings in this format, where \fIx\fP is can be any character, are defined by the
specific macro package in use and are not specified by \fIbib\fP.
.IP \fIx\fP]
If \fIx\fP is nonalphanumeric these strings represent formatting commands following
citations (the inverse of [\fIx\fP commands).  Other strings represent
miscellaneous formatting commands,
such as the space between leading letters in abbreviated names.
.PP
There are two such macro names to be particularly aware of: .s[ and .e[\&.
The first is called at the beginning of formatting a reference and the
latter is called at the end of the formatting.  
The user can have some
control over the formatting of
references by redefining these macros.
.PP
It might be noted here that the best way to understand this stuff is to
look at some existing definition files, and start making small changes
here and there.
.SH
Sort Templates
.PP
The sort template is used in comparing two references to generate
the sorted reference list.  The sort template is a sequence of
sort objects.  Each sort object consists of an optional negative sign, followed
by a field character, followed by an optional signed size.  The leading negative
sign, if present, specifies the sort is to be in decreasing order, rather than
increasing.  The field character indicates which field in the reference
is to be compared.  The entire field is used, except in the case of the `A'
field, in which case only the senior author's last name is used.
A positive number following the field character indicates that only the first
n characters are to be examined in the comparison.  The negative value indicates
only the last \fIn\fP characters.  
Thus, for example, the template AD\-2 indicates
that sorting is to be done by the senior author followed by the last two
characters of the date.
.PP
The sort algorithm is stable, so that two documents which compare equally
will be listed in citation order.
.PP
Note that in sorting, citation construction, and elsewhere, if an author
field is not present the senior editor will be used.  If neither author nor
editor fields are present the institution name will be used.
.SH
Citation Templates
.PP
A citation template is similar to a sort template, with the following
additions:  
.IP 0
suppresses all printing. \fB[[True?  can anyone tell me what this does?]]\fP
.IP 1
refers to the number which
represents the position of the reference in the reference list (after sorting).
.IP 2
generates a three character sequence: if the
paper being referenced has only one author, this is the first three characters
of the author's last name; for two author papers, this is the first two
characters of the senior author, followed by the first character of the second
author; for papers with three or more authors the first letter of the first
three authors is used.
.IP 3
used to specify a format consisting of the authors'
last names, or the senior author followed by the text `et al' if more than
four authors are listed.  This is the Astrophysical Journal style of
citation.
.IP 4
the Computing Surveys style of citation.
.IP 8
full alphabetic.
.IP 9
last name of senior author.
.PP
.PP
Each object can be followed by either of the letters `u' or
`l' and the field will be printed in all upper or all lower case,
respectively.
.PP
If necessary for disambiguating, the character `@' can be used as
a separator between objects in the citation template.  Any text which should
be inserted into the citation uninterpreted should be surrounded by either
\&'{\&..}' or '<\&..>' pairs.
.SH
Citation Formatting in Troff
.PP
In the output, each citation is surrounded by the strings \e*([[ and \e*(]]
(or in the alternative style \e*([{ and \e*(}]).
Multiple citations are separated by the string \e*(],.
The text portion of a format file should contain \fItroff\fP definitions for
these strings to achieve the appropriate typographic effect.
.PP
Citations that are preceded by a period, comma, space or other punctuation
are surrounded by string values for formatting the punctuation in the
appropriate location.
Again, \fItroff\fP commands should be given to insure the appropriate values 
are produced.
.KS
.PP
The following table summarizes the string values that must be defined
to handle citations.
.TS
center;
l l l.
[[	]]	Standard citation beginning and ending
{[	}]	Alternate citation beginning and ending
[\&.	.]	Period before and after citation
[,	,]	Comma before and after citation
[?	?]	Question mark before and after citation
[!	!]	Exclamation Point before and after citation
[:	:]	Colon before and after citation
[;	;]	Semi-Colon before and after citation
["	"]	Double Quote before and after citation
['	']	Single Quote before and after citation
[<	>]	Space before and after citation
],		Multiple citation separator
]-		Separator for a range of citations
.TE
.KE
.SH
Name Formatting in Troff
.PP
Authors' (and editors') names can be abbreviated, reversed, and/or printed
in Caps-small Caps format.  In producing the string values for an author,
formatting strings are inserted to give the macro writer greater flexibility
in producing the final output.  Currently the following strings are used:
.TS
center;
l l.
a]	gap between successive initials
b]	comma between last name and initial in reversed text
c]	comma between authors
n]	\fIand\fP between two authors
m]	\fIand\fP between last two authors
p]	period following initial
.TE
.PP
For example, suppose the name `William E. Howden' is abbreviated
and reversed.  It will come out looking like
.ce
Howden\\*(b]W\\*(p]\\*(a]E\e*(p]
.SH
Reference Formatting in Troff
.PP
The particular style used in printing references is decided by macros
passed to \fItroff\fP.  Basically, for each reference,
\fIbib\fP generates a sequence of string definitions, one for each field in the
reference, followed by a call on the formatting macro.  For example an
entry which in the reference file looks like:
.KS
.nf
.ta 3m
.sp
%A	M. A. Harrison
%A	W. L. Ruzzo
%A	J. D. Ullman
%T	Protection in Operating Systems
%J	CACM
%V	19
%N	8
%P	461-471
%D	1976
%K	hru
.sp
.KE
.LP
is converted into the following sequence of \fItroff\fP commands
.KS
.nf
.sp
 .[\-
 .ds [F 1
 .ds [A M\e*(p]\e*(a]A\e*(p] Harrison
 .as [A \e*(c]W\e*(p]\e*(a]L\e*(p] Ruzzo
 .as [A \e*(m]J\e*(p]\e*(a]D\e*(p] Ullman
 .ds [T Protection in Operating Systems
 .ds [J Communications of the ACM
 .ds [V 19
 .ds [N 8
 .nr [P 1
 .ds [P 461-471
 .ds [D 1976
 .ds [K hru
 .][
.sp
.KE
.PP
Note that the commands are preceded by a call on the macro `.[\-'.
This can be used by the macro routines for initialization, for example to
delete old string values.  (For some reason, the ending macro .e[ also calls
.[\- which seems redundant.)
.PP
The string [F is the citation string used in the document.
Note that the string CACM has been expanded.
.PP
The strings c], n] and m] are used to separate authors.  c] separates
the initial authors in multi-author documents (it is usually a comma
with some space before and after), n] separates authors in two author
documents (usually `\ and\ '), and m] separates the last two authors
in multi-author documents (either `\ and\ ' or `,\ and\ ').
.PP
If abbreviation is specified, the string a] is used to separate initials
in the author's first name, and the string p] determines the punctuation
to use (usually a period).
.PP
The \fIbib\fP system provides minimal assistance in
deciding format types.  For example note that the number register [P has
been set of 1, to indicate that the article is on more than one page.
Similarly, in documents with editors, the register [E is set to the number
of editors.
.SH
Trailing Characters
.PP
There is a problem with fields that end with punctuation characters causing
multiple occurrences of those characters to be printed.  For example, suppose
author fields are terminated with a period, as in T. A. Budd.  If names
are reversed, this could be printed as Budd, T. A..  Even if names are not
reversed, abbreviations, such as in Jr. can cause problems.
.PP
To avoid this problem \fIbib\fP, if instructed, generates the last
character from a particular field as a separate string.  The string name
is a right brace  followed by the field character (e.g. ]A for the
author field).  Macro packages should
test this value before generating punctuation.
.SH
Abbreviations
.PP
The algorithm used to generate abbreviations from first names is fairly
simple: Each word in the first name field that begins with a capital
is reduced to that capital letter followed by a period.
In some cases, this may not be sufficient.  For example, suppose
Ole-Johan Dahl should be abbreviated `O\-J. Dahl'.  The only
way to achieve this (short of editing the output) is to include \fItroff\fP commands
in the reference file that alter the strings produced by \fIbib\fP, as in the following
.RS
.sp
 ...
 %A Ole-Johan Dahl
 .ds [A O\-J. Dahl
 ...
.sp
.RE
.PP
In fact, if absolutely necessary, any \fItroff\fP 
commands can be entered in the middle of a reference
entry, and the commands are copied uninterpreted to the output.
For example, the user may wish to have a switch indicating whether the name
is to be abbreviated or not:
.RS
.sp
 ...
 %A Ole-Johan Dahl
 .if \en(i[ .ds [A O\-J. Dahl
 ...
.sp
.RE
.PP
However, keep in mind the restrictions this imposes on the portability
and convertibility of the database.
.bp
.SH
An Example
.PP
Figure 1 shows the format file for the standard alphabetic format.
The I command includes a file of definitions
for common strings, such as dates and journal names.  A portion of this
file is shown in figure 2.
The sort command indicates that sorting is to be done by senior author,
followed by the last two digits of the date.  The citation template
indicates that citations will be a three character sequence 
followed by the last two characters of the date (e.g. AHU79)
(described in the section on citations above).
Author and editor names will be abbreviated.