NAME
nbibtex - make a bibliography for LaTeX
SYNOPSIS
nbibtex [options] auxname[.aux] [bibname...]
DESCRIPTION
NbibTeX is a drop-in replacement for BibTeX. It reads the top-level
auxiliary (.aux) file that was output during the running of latex(1) or
tex(1) and creates a bibliography (.bbl) file that will be incorporated
into the document on subsequent runs of LaTeX or TeX.
NbibTeX looks up, in bibliographic database (.bib) files specified by
the \bibliography command, the entries specified by the \cite and
\nocite commands in the LaTeX or TeX source file. The association of
\cite command with .bib entry is made by a simple query language
described below. NbibTeX formats the information from the .bib entries
according to instructions in a bibliography style (.nbs) file
(specified by the \bibliographystyle command, and it outputs the
results to the .bbl file.
If the optional bibnames are used, NbibTeX looks in the named
bibliographies instead of those specified by the \bibliography command.
A bibname without a slash (/) character means the same thing it would
mean in a \bibliographystyle command: it is looked up according to the
rules of BibTeX. A bibname with a slash character is taken to be the
absolute or relative pathname of a .bib file. Explicit bibnames can be
used with the -bib and -o options to make a paper-specific .bib file
from larger .bib files.
The LaTeX manual explains what a LaTeX source file must contain to work
with NbibTeX. Appendix B of the manual describes the format of the
.bib files. The ‘NbibTeXing’ document describes extensions and details
of this format, and it gives other useful hints for using NbibTeX.
OPTIONS
-min-crossrefs=number
The -min-crossrefs option defines the minimum number of crossref
required for automatic inclusion of the crossref’d entry on the
citation list; the default is 2.
-terse Accepted for backward compatibility with BibTeX; NbibTeX is
terse by default.
-permissive
Enables NbibTeX to continue working even when some of the .bib
files mentioned in the \bibliography command are missing. Also
tells NbibTeX not to object if duplicate entries are found in
multiple .bib files.
-strict
Tells NbibTeX to complain about all irregularities it spots in
any .bib file it parses. By default, NbibTeX (like BibTeX)
complains only about entries it actually intends to use.
-o file
Writes the bibliography to file instead of to the default
auxname.bbl. If file is -, writes to standard output.
-bib Instead of writing a bibliography for use by LaTeX, writes
exactly those NbibTeX entries needed by auxname. Useful for
making paper-specific .bib files.
-help Emit a short help message and exit.
-version
Emit version information and exit.
EXAMPLES
To make a normal bibliography for file paper.tex:
nbibtex paper
To use the personal .bib file personal.bib to make a paper-specific
bibliography for file paper.tex, which should use the command
lography{paper}:
nbibtex -o paper.bib -bib paper personal
The file personal.bib should be found on the usual BIBINPUTS path.
To extend the bibliography paper.bib by filling in missing entries from
personal.bib:
nbibtex -permissive -o paper.bib -bib paper paper personal
QUERY LANGUAGE
To specify a paper you wish to cite, classic BibTeX requires an
arbitrary key. The advantage of NbibTeX is that you cite a paper by
the contents of the NbibTeX entry.
The citation consists of a sequence of one or more constraints
separated by colons. A constraint may be empty.
A nonempty constraint is of the form key=words, where key is the
name of a field in the NbibTeX entry and words is a sequence of
one or more words separated by dashes. The contraint is
satisfied if every word in words is found in the field named by
key. (The key may also be [type], which matches agains the type
of the entry, or *, which looks for words in any field.)
For example, the following queries might match an entry for a useful
source on arithmetic:
author=knuth:series=art-programming:volume=2
author=knuth:title=seminumerical:year=1981
As a convenience, keys may be defaulted in up to three constraints. In
the first constraint, the default key is author (or if there is no
author, editor). In the second constraint, the default key is year if
words is all digits, and is title otherwise. In the third constraint,
the default key is year if words is all digits, and is [type]
otherwise. So for example, we could have written
knuth:seminumerical:1981
To match a word in words, ΒX uses the Boyer-Moore string-matching
algorithm, so longer words are usually faster.
NbibTeX’s query language can be used on the command line by
nbibfind(1).
NBIBTEX STYLES AND COMPATIBILITY WITH BibTeX
Like BibTeX, NbibTeX supports a variety of "styles" of bibliography.
Each style is defined by a program written in Lua, using additional
primitives suitable to construction of bibliographies. NbibTeX
provides the three standard styles in a form suitable for use with the
natbib package. Two of these styles (abbrvnat and unsrtnat) are
completely compatible with the corresponding BibTeX styles; the third
style (plainnat) has been changed to more closely follow the Chicago
Manual of Style. A compatible version is available as style plainnatc.
Additional styles may be created by writing new Lua code; for example,
an author wishing to create a style called mcbride would put a file
called mcbride.nbs (for New BibTeX Style) in the directory
/usr/share/nbibtex. For guidance on what goes into such a file,
consult the other files in that directory and the literate source code
for NbibTeX.
ENVIRONMENT
For .bib files, NbibTeX searches the directories in the path defined by
the BIBINPUTS environment variable if that is set, otherwise the
default. For details of the searching, see tex(1) and kpsewhich(1).
No special searching is done for the .aux file.
FILES
/usr/share/nbibtex/*.nbs
New bibliography style files.
BUGS
Although I have made some effort in this direction, compatibility with
BibTeX does not extend to .bib files containing non-ASCII characters.
SEE ALSO
nbibfind(1), latex(1), tex(1), kpsewhich(1), bibtex(1).
Leslie Lamport, LaTeX - A Document Preparation System, Addison-Wesley,
1985, ISBN 0-201-15790-X.
The NbibTeX home page at http://www.eecs.harvard.edu/~nr/nbibtex.
The Lua home page at http://www.lua.org.
AUTHOR
Norman Ramsey, Harvard University.
15 May 2006