bibdoc.ms

早期freebsd实现

.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)bibdoc.ms	8.1 (Berkeley) 6/8/93
.\"
.EH 'USD:28-%''BIB \- A Program for Formatting Bibliographies'
.OH 'BIB \- A Program for Formatting Bibliographies''USD:28-%'
.nr LL 6.5i
.nr LT 6.5i
.TL
\fBBIB \- A Program for Formatting Bibliographies\fP
.AU
Timothy A. Budd
revised by A. Dain Samples, \*(td
.PP
\fIBib\fP is a program for collecting and formatting reference lists in
documents.  It is a preprocessor to the nroff/troff typesetting systems,
(much like the \fItbl\fP [.tbl.] and \fIeqn\fP [.eqn.] programs) and an alternative
to the \fIrefer\fP [.lesk refer.]  and \fItib\fP [.alexander tib.] 
bibliography programs.
\fIBib\fP takes two
inputs: a document to be formatted and a library of references.  Imprecise
citations in the source document are replaced by more conventional
citation strings, the appropriate references are selected from the reference
file, and commands are generated to format both citation and the referenced
item in the bibliography.
.PP
\fIBib\fP has been enhanced to promote sharing of bibliographic
references from the \fIrefer\fP,
\fIbib\fP, and Tib tools.  \fIBib\fP now accepts the Tib style of macro 
invocation, i.e. surrounding names that are to be expanded with vertical bars.
If you or your group are not contemplating
moving to the TeX or LaTeX [.knuth tex, lamport latex.] 
text processors, then you need not worry
about any of the references to Tib in this document.
However, if you are considering such a
move, and are worried about how you will convert your bibliographic
databases to the BibTeX format, then the current version of \fIbib\fP,
in conjunction with the existing Tib software\u1\d 
.FS
1. Tib is available, for a handling charge, from James C. Alexander at the 
Dept. of Mathematics,
University of Maryland, College Park, MD 20742.  It is also available
from \fBeneevax.umd.edu:pub/tib\fP via \fIftp\fP.
.FE
will make life a lot easier for you.
.SH
Description
.PP
An imprecise citation is a list of words surrounded by the characters
[\&. and .].  Words (which are truncated to six letters)
in the imprecise citation are matched against entries in the reference file,
and if an entry is found that matches all words, that reference is used.
For example:
.de 2Q
.sp
.RS
.RS
..
.de 2E
.sp
.RE
.RE
..
.2Q
.PP
In Brooks' interesting book [\&. brooks mythical.] various reasons ...
.2E
.PP
Multiple citations are indicated by simply placing a comma in the imprecise
citation:
.2Q
.PP
In [\&.kernig tools, kernig elements.], Kernighan and Plauger have ...
.2E
.PP
Embedded newlines, tabs and extra blanks within the
imprecise citation are ignored.
.PP
Judicious use of the K (keyword) field in references in the database
can simplify citations
considerably.  Also additional information can be placed into citations by
surrounding text with curly braces.
The additional information is inserted verbatim into the citation,
e.g. [.dragon {,\ Chapter 6}.].
Note that it may be desirable to use non-breakable spaces, in order that the
citation not be split across a line boundary by \fItroff\fP, for example:
.2Q
.PP
For a description of LR parsing, see [\&.dragon {,\e\0Chapter 6}.] by Aho and Ullman.
.2E
.PP
The angle brackets can be used as alternatives to the curly braces.
.2Q
.PP
For a description of LR parsing, see [\&.dragon <,\e\0Chapter 6>.] by Aho and Ullman.
.2E
.PP
An alternative citation style can be used by surrounding the imprecise
citation with {\&. and .\&}.  Most document styles just give the
raw citation, without the braces, in this case.  This is useful, for example,
to refer to citations in running text.
.2Q
.PP
For a discussion of this point, see reference {\&.dragon.\&}.
.2E
.PP
The algorithm used by \fIbib\fP scans the source input in two passes.
In the first pass,
references are collected and the location of citations marked.
In the second pass, these marks are replaced by the appropriate citation,
and the entire list of references is dumped following a call on the macro
\&.[].
This macro is left untouched.
However, this can be altered to achieve other typographic
effects.
.PP
An exception to this process is made in those instances where
references are indicated in footnotes.  In this case the macro that
generates the reference is placed immediately after each line in which
the reference is cited.
.SH
Creating the Database
.PP
Reference files are prepared for \fIbib\fP using \fIinvert\fP.
By default \fIinvert\fP places an inverted index for the
reference list in the file INDEX.  Unless the user specifies an
alternative (see the \-p switch described below), this is the first file
searched by \fIbib\fP in attempting to locate a reference.  
If the entry is not found
in the user's file, a standard system-wide index is searched.  If the
entry is still not found in the system file, a warning message is produced
and a blank citation is generated.
.PP
The format for entries in the reference file is described more fully in
the section `Reference File Formats'.
.PP
Since the user's index is searched before the system index, if the
user wants to alter a specific entry in the system index (say to change
the name W. E. Howden to William E. Howden, for example) it is a simple
matter to copy the system information into a private database and make
the changes locally.
\fIBib\fP issues messages warning the user if there are multiple entries
in a reference file that match an imprecise reference, or if there are
multiple index files that match an imprecise reference.  (Note that
previous versions of \fIbib\fP stopped searching after the first match
was found.  Current users of \fIbib\fP may see warning messages now that
they did not receive before.)
The `duplicate matches' warning message can be controlled by making the 
citations more precise. 
.PP
Citation formats are either determined by explicit switch settings or,
more generally, by using a predefined formatting style.  In the latter form,
usage looks something like:
.sp
.ce
bib \-t\fIstyle\fP [files]
.sp
where \fIstyle\fP is a citation style.
Currently the following citation styles are available:
.IP astro 6m
astrophysical journal style references
.IP compsurv
Computing Surveys style references
.IP foot
footnoted references.
.IP hnf
Hanson Normal Form
.IP jrnl
lists references in alphabetical and date order by journal; see Miscellaneous 
Tools section.
.IP lib
useful for printing the entire bibliography; see Miscellaneous Tools
section
.IP list
a useful format for listrefs, which see.
.IP llist
another useful format for printing everything about your bibliography
database; see Miscellaneous Tools section
.IP opena
same as stda, but using an open format.
.IP openn
same as stdsn, only using an open reference format (each major entry is on
a new line\u1\d).
.FS
1. The open reference format is adapted from \fIA Handbook for Scholars\fP,
by Mary-Claire van Leunen, published by Knopf, 1978.
.FE
.IP spe
format used by the journal \fISoftware\(emPractice and Experience\fP.
.IP spe2
a second format for \fISoftware\(emPractice and Experience\fP.  
.IP stda
standard alphabetic format, where 
citations are three letters followed by the last two
digits of the date; for papers with a single author, the letters are the
first three letters of the authors last name (e.g. Knu);
in papers with two authors the first two letters are from the first author
followed by one letter from the second (e.g. HoU); etc.
(see the section \fBCitation Templates\fP under
\fBReference Format Desiner's Guide\fP for more details).
.IP stdafull
standard alphabetic format, with full references.
.IP stdn
standard numeric citation; reference entries are listed in order of mention.
.IP stdsn
same as stdn, but references are sorted by senior author followed by date.
.IP supn
same as stdn, but using superscripts.
.PP
It is possible to alter slightly the format of standard styles.  For example,
to generate references in standard numeric style with first names
abbreviated:
.sp
.ce
bib \-tstdn \-aa ...
.PP
If two reference items create the same citation string (this can happen
if two works by the same authors published in a single year are referred to
in one paper) a disambiguating final letter is added to the citation
(i.e., Knu79 becomes Knu79a and Knu79b).
This can be altered by using the F field (see the section on Reference File
Formats).
.PP
For the purposes of sorting by author, the last name is taken to be the last
word of the name field.  This means some care must be taken when names contain
embedded blanks, such as in `Hartley Rogers, Jr.'
or `Mary-Claire van Leunen'.
In these cases a concealed space (\e\0) should be used, as in
`Hartley Rogers,\e\0Jr.'.
.PP
\fIbib\fP knows very little about \fItroff\fP usage or syntax.  This
can sometimes be useful.  For example, to cause an entry to appear in a
reference list without having it explicitly cited in the text the citation
can be placed in a \fItroff\fP comment.
.RS
.nr
.sp
 .\e" [\&.imprecise citation.]
.sp
.RE
.PP
It is also possible to embed \fItroff\fP commands within a reference definition.
See `Abbreviations' in the section `Reference Format Designer's
Guide' for an example.  However, be aware that unbridled use of such
embedded processor-specific commands makes it more difficult to convert
to other processors later.  In the section on Miscellaneous Tools, we
discuss ways to avoid such specificity.
.PP
In some styles (superscripts) periods and commas should precede the
citation while spaces follow.
In other styles (brackets) these rules are reversed.  If
a period, comma or space immediately precedes a citation, it will be moved to the
appropriate location for the particular reference style being used.
This movement is not done for citations given in the alternative style
(i.e. {\&.dragon.}).
.PP
The following is a complete list of options for \fIbib\fP:
.IP \-aa 8m
reduce author's first names to abbreviations.
.IP \-ar\fInum\fP
reverse the first \fInum\fP author's names.
If \fInum\fP is omitted all names are reversed.
.IP \-ax
print authors last names in Caps-Small Caps style.  For example Budd becomes
B\s-2UDD\s+2.
.IP \-c\fIstr\fP
build citations according to the template \fIstr\fP;  
see the section \fBCitation Templates\fP under
\fBReference Format Desiner's Guide\fP for the format of the string and
its effect.
.IP "\-d \fIdir\fP"
.ns
.IP "\-d\fIdir\fP"
change the base directory in which files are sought.  It is initially
/usr/new/lib/bmac.
.IP \-ea
abbreviate editors' names
.IP \-ex
places editors' names in Caps-Small Caps style.  (see \-x )
.IP \-er\fInum\fP
reverse the first \fInum\fP editors' names.  
If \fInum\fP is omitted all editors'
names are reversed.
.IP \-f
instead of dumping references following the call on \&.[], dump each
reference immediately following the line on which the citation is placed
(used for footnoted references).
.IP \-h
hyphenate runs of three or more contiguous references in the citation string.
(eg 2,3,4,5 becomes 2-5).  This is most useful for numeric citation styles,
but works generally.
The \-h option implies the \-o option.
.IP "\-i file"
.ns
.IP "\-ifile"
include and process the indicated file.
This is useful for including a private file of string definitions.
.IP \-n\fIstr\fP
turn off the indicated options.  \fIstr\fP must be composed of the
characters \fIafhoRrvx\fP.
.IP \-o
sort contiguous citations according to the order given by the reference
list.  (This option defaults on).
.IP "\-p \fIfile\fP"
.ns
.IP  \-p\fIfile\fP
instead of searching the file INDEX,
search the indicated reference file(s) before searching the system file.
Multiple files are separated by commas.
.IP \-R
print a warning each time there is an attempt to redefine a name.  (No warning
is the default.)
.IP \-r\fInum\fP
synonym for \-ar.
.IP \-s\fIstr\fP
sort references according to the template \fIstr\fP.
.IP "\-t \fItype\fP"
.ns
.IP \-t\fItype\fP
use the standard macros and switch settings to generate citations and references
in the indicated style.
.IP \-Tib
use the Tib macro conventions.  See the discussion in the Reference Format 
Designer's Guide.
.IP \-Tibx
creates the file .bib.m4.in in the current directory.  This file
contains macro definitions that when applied to a database file,
converts calls on macros to the form expected by the Tib
bibliography preprocessor; more information is in the section 
Miscellaneous Tools.
.IP \-v
\fB[[I'm not sure what this does; it is related to the \-f option, but
it apparently suppresses the printing of certain
information.]]\fP
.IP \-x
synonym for \-ax.
.PP
When a file is to be included during normal \fIbib\fP processing
(options \-i and \-t, and the style file command I)
\fIbib\fP searches a specific set of directories and filenames.
For example, if \fB-i myfile\fP is specified on the invocation line, 
\fIbib\fP attempts to open, in order, the following files until one is
found.  
.IP 1.
\fI\&./myfile\fP
.IP 2.
\fBBMACLIB\fP\fI/myfile\fP, where \fBBMACLIB\fP is defined by the \-d
option (default: /usr/new/lib/bmac).
.IP 3.
\fBBMACLIB\fP\fI/tibmacs/myfile\fP if \-Tib was specified, otherwise
\fBBMACLIB\fP\fI/bibmacs/myfile\fP
.IP 4.
\fI\&./bib.myfile\fP
.IP 5.