[This document will be expanded when
version 1.00 comes out. Please report typos, omissions, inaccuracies, and especially unclear explanations to me (patashnik@SCORE.STANFORD.EDU). Suggestions for improvements are wanted and welcome.]
This documentation, for
version 0.99b, is meant for general
users; bibliography-style designers should read this document and then read ``Designing
Styles'' [3], which is meant for just them.
This document has three parts: Section 2 describes the differences between versions 0.98i and 0.99b of
and between the corresponding versions of the standard styles; Section 3 updates Appendix B.2 of the LATEX book [2]; and Section 4 gives some general and specific tips that aren't documented elsewhere. It's assumed throughout that you're familiar with the relevant sections of the LATEX book.
This documentation also serves as sample input to help
implementors get it running. For most documents, this one included, you produce the reference list by: running LATEX on the document (to produce the aux file(s)), then running
(to produce the bbl file), then LATEX twice more (first to find the information in the bbl file and then to get the forward references correct). In very rare circumstances you may need an extra /LATEX run.
version 0.99b should be used with LATEX version 2.09, for which the closed bibliography format is the default; to get the open format, use the optional document style openbib (in an open format there's a line break between major blocks of a reference-list entry; in a closed format the blocks run together).]
Note:
0.99b is not compatible with the old style files; nor is
0.98i compatible with the new ones (the new , however, is compatible with old database files).
Note for implementors:
provides logical-area names TEXINPUTS: for bibliography-style files and TEXBIB: for database files it can't otherwise find.
This section describes the differences between
versions 0.98i and 0.99b, and also between the corresponding standard styles. There were a lot of differences; there will be a lot fewer between 0.99 and 1.00.
features
The following list explains 's new features and how to use them.
\nocite{*}
' you can now include
in the reference list every entry in the database files, without having
to explicitly \cite
or \nocite
each entry.
Giving this command, in essence, \nocite
s all the enties
in the database, in database order, at the very spot in your document
where you give the command.
@STRING( WGA = " World Gnus Almanac" )then it's easy to produce nearly-identical title fields for different entries:
@BOOK(almanac-66, title = 1966 # WGA, . . . @BOOK(almanac-67, title = 1967 # WGA,and so on. Or, you could have a field like
month = "1~" # jan,which would come out something like `
1~January
' or
`1~Jan.
' in the bbl file, depending on how
your bibliography style defines the jan abbreviation. You
may concatenate as many strings as you like (except that there's a
limit to the overall length of the resulting field); just be sure
to put the concatenation character `#', surrounded
by optional spaces or newlines, between each successive pair of strings.
has a new cross-referencing feature, explained by an example. Suppose
you say \cite{no-gnats}
in your document, and suppose
you have these two entries in your database file:
@INPROCEEDINGS(no-gnats, crossref = "gg-proceedings", author = "Rocky Gneisser", title = "No Gnats Are Taken for Granite", pages = "133-139") . . . @PROCEEDINGS(gg-proceedings, editor = "Gerald Ford and Jimmy Carter", title = "The Gnats and Gnus 1988 Proceedings", booktitle = "The Gnats and Gnus 1988 Proceedings")Two things happen. First, the special crossref field tells
that the no-gnats entry should inherit any fields it's missing from the entry it cross references, gg-proceedings. In this case it in inherits the two fields editor and booktitle. Note that, in the standard styles at least, the booktitle field is irrelevant for the PROCEEDINGS entry type. The booktitle field appears here in the gg-proceedings entry only so that the entries that cross reference it may inherit the field. No matter how many papers from this meeting exist in the database, this booktitle field need only appear once.
The second thing that happens:
automatically puts the entry gg-proceedings into
the reference list if it's cross referenced by two or more entries
that you \cite
or \nocite
, even if you don't
\cite
or \nocite
the gg-proceedings
entry itself. So gg-proceedings will automatically
appear on the reference list if one other entry besides no-gnats
cross references it.
To guarantee that this scheme works, however, a cross-referenced entry must occur later in the database files than every entry that cross-references it. Thus, putting all cross-referenced entries at the end makes sense. (Moreover, you may not reliably nest cross references; that is, a cross-referenced entry may not itself reliably cross reference an entry. This is almost certainly not something you'd want to do, though.)
One final note: This cross-referencing feature is completely unrelated to the old 's cross referencing, which is still allowed. Thus, having a field like
note = "Jones \cite{jones-proof} improves the result"is not affected by the new feature.
now handles accented characters. For example if you have an entry with the two fields
author = "Kurt G{\"o}del", year = 1931,and if you're using the alpha bibliography style, then
will construct the label [Göd31] for this entry, which
is what you'd want. To get this feature to work you must place the
entire accented character in braces; in this case either {\"o}
or {\"{o}}
will do. Furthermore these braces must not
themselves be enclosed in braces (other than the ones that might delimit
the entire field or the entire entry); and there must be a backslash
as the very first character inside the braces. Thus neither {G{\"{o}}del}
nor {G\"{o}del}
will work for this example.
This feature handles all the accented characters and all but the nonbackslashed foreign symbols found in Tables 3.1 and 3.2 of the LATEX book. This feature behaves similarly for ``accents'' you might define; we'll see an example shortly. For the purposes of counting letters in labels,
considers everything contained inside the braces as a single letter.
also handles hyphenated names. For example if you have an entry with
author = "Jean-Paul Sartre",and if you're using the abbrv style, then the result is `J.-P. Sartre'.
@PREAMBLE
command
for the database files. This command's syntax is just like @STRING
's,
except that there is no name or equals-sign, just the string. Here's
an example: @PREAMBLE{ "\newcommand{\noopsort}[1]{} " # "\newcommand{\singleletter}[1]{#1} " }(note the use of concatenation here, too). The standard styles output whatever information you give this command (LATEX macros most likely) directly to the bbl file. We'll look at one possible use of this command, based on the
\noopsort
command
just defined.
The issue here is sorting (alphabetizing).
does a pretty good job, but occasionally weird circumstances conspire to confuse : Suppose that you have entries in your database for the two books in a two-volume set by the same author, and that you'd like volume 1 to appear just before volume 2 in your reference list. Further suppose that there's now a second edition of volume 1, which came out in 1973, say, but that there's still just one edition of volume 2, which came out in 1971. Since the plain standard style sorts by author and then year, it will place volume 2 first (because its edition came out two years earlier) unless you help . You can do this by using the year fields below for the two volumes:
year = "{\noopsort{a}}1973" . . . year = "{\noopsort{b}}1971"According to the definition of
\noopsort
, LATEX will
print nothing but the true year for these fields. But
will be perfectly happy pretending that \noopsort
specifies
some fancy accent that's supposed to adorn the `a' and the `b'; thus
when
sorts it will pretend that `a1973' and `b1971' are the real years,
and since `a' comes before `b', it will place volume 1 before
volume 2, just what you wanted. By the way, if this author has any
other works included in your database, you'd probably want to use
instead something like {\noopsort{1968a}}1973
and {\noopsort{1968b}}1971
,
so that these two books would come out in a reasonable spot relative
to the author's other works (this assumes that 1968 results in a reasonable
spot, say because that's when the first edition of volume 1 appeared).
There is a limit to the number of @PREAMBLE
commands
you may use, but you'll never exceed this limit if you restrict yourself
to one per database file; this is not a serious restriction, given
the concatenation feature (item 2).
no longer does case conversion for file names; this will make
easier to install on Unix systems, for example.
This section describes changes to the standard styles (plain, unsrt, alpha, abbrv) that affect ordinary users. Changes that affect style designers appear in the document ``Designing
Styles'' [3].
~
) have been removed. LATEX thus
will produce slightly fewer `Underfull
\hbox
' messages when it's formatting the reference list.
{\em ...}
) has replaced italicizing ({\it ...}
).
This will almost never result in a difference between the old output
and the new.
\etalchar
command that the alpha style writes onto the bbl
file (just preceding the \thebibliography
environment);
use LATEX's \renewcommand
inside a database @PREAMBLE
command, described in the previous subsection's item 6.
\cite
of the cross-referenced entry and by omitting
from the cross-referencing entry (most of the) information that appears
in the cross-referenced entry. These styles do this when a titled
thing (the cross-referencing entry) is part of a larger titled thing
(the cross-referenced entry). There are five such situations: when
(1) an INPROCEEDINGS (or CONFERENCE,
which is the same) cross references a PROCEEDINGS;
when (2) a BOOK, (3) an INBOOK, or (4) an
INCOLLECTION cross references a BOOK (in
these cases, the cross-referencing entry is a single volume in a multi-volume
work); and when (5) an ARTICLE cross references
an ARTICLE (in this case, the cross-referenced entry
is really a journal, but there's no JOURNAL entry
type; this will result in warning messages about an empty author
and title for the journal--you should just ignore
these warnings).
type = "{Ph.D.} dissertation"in your database entry.
chapter = "1.2", type = "Section"in your database entry.
titles rather than BOOK
titles.
This section is simply a corrected version of Appendix B.2 of the LATEX book [2], © 1986, by Addison-Wesley. The basic scheme is the same, only a few details have changed.
When entering a reference in the database, the first thing to decide is what type of entry it is. No fixed classification scheme can be complete, but
provides enough entry types to handle almost any reference reasonably well.
References to different types of publications contain different information; a reference to a journal article might include the volume and number of the journal, which is usually not meaningful for a book. Therefore, database entries of different types have different fields. For each entry type, the fields are divided into three classes:
ignores any field that is not required or optional, so you can include any fields you want in a bib file entry. It's a good idea to put all relevant information about a reference in its bib file entry--even information that may never appear in the bibliography. For example, if you want to keep an abstract of a paper in a computer file, put it in an abstract field in the paper's bib file entry. The bib file is likely to be as good a place as any for the abstract, and it is possible to design a bibliography style for printing selected abstracts. Note: Misspelling a field name will result in its being ignored, so watch out for typos (especially for optional fields, since
won't warn you when those are missing).
\bibitem
label.
You should include a key field for any entry whose
``author'' information is missing; the ``author'' information
is usually the author field, but for some entry types
it can be the editor or even the organization
field (Section 4 describes this in more detail).
Do not confuse the key field with the key that appears
in the \cite
command and at the beginning of the database
entry; this field is named ``key'' only for compatibility with
Scribe.
Below is a description of all fields recognized by the standard bibliography styles. An entry can also contain other fields, which are ignored by those styles.
\cite
command and at the beginning of the database
entry.
This section gives some random tips that aren't documented elsewhere, at least not in this detail. They are, roughly, in order of least esoteric to most. First, however, a brief spiel.
I understand that there's often little choice in choosing a bibliography style--journal says you must use style and that's that. If you have a choice, however, I strongly recommend that you choose something like the plain standard style. Such a style, van Leunen [4] argues convincingly, encourages better writing than the alternatives--more concrete, more vivid.
The Chicago Manual of Style [1], on the other hand, espouse the author-date system, in which the citation might appear in the text as `(Jones, 1986)'. I argue that this system, besides cluttering up the text with information that may or may not be relevant, encourages the passive voice and vague writing. Furthermore the strongest arguments for using the author-date system--like ``it's the most practical''--fall flat on their face with the advent of computer-typesetting technology. For instance the Chicago Manual contains, right in the middle of page 401, this anachronism: ``The chief disadvantage of [a style like plain] is that additions or deletions cannot be made after the manuscript is typed without changing numbers in both text references and list.'' LATEX, obviously, sidesteps the disadvantage.
Finally, the logical deficiencies of the author-date style are quite evident once you've written a program to implement it. For example, in a large bibliography, using the standard alphabetizing scheme, the entry for `(Aho et al., 1983b)' might be half a page later than the one for `(Aho et al., 1983a)'. Fixing this problem results in even worse ones. What a mess. (I have, unfortunately, programmed such a style, and if you're saddled with an unenlightened publisher or if you don't buy my propaganda, it's available from the Rochester style collection.)
Ok, so the spiel wasn't very brief; but it made me feel better, and now my blood pressure is back to normal. Here are the tips for using
with the standard styles (although many of them hold for nonstandard styles, too).
from changing something to lower case, you enclose it in braces. You might not get the effect you want, however, if the very first character after the left brace is a backslash. The ``special characters'' item later in this section explains.
allows in the database files any comment that's not within an entry. If you want to comment out an entry, simply remove the `@' character preceding the entry type.
\bibliography
command (but you should list this argument before the ones that specify
real database entries).
month = jul # "~4,"will probably produce just what you want.
\nocite{*}
feature
(all entries in the database are included), the placement of the \nocite{*}
command within your document file will determine the reference order.
According to the rule given in Section 2.1: If the command
is placed at the beginning of the document, the entries will be listed
in exactly the order they occur in the database; if it's placed at
the end, the entries that you explicitly \cite
or \nocite
will occur in citation order, and the remaining database entries will
be in database order.
author = "Donald E. Knuth" . . . author = "D. E. Knuth"There are two possibilities. You could (1) simply leave them as is, or (2) assuming you know for sure that these authors are one and the same person, you could list both in the form that the author prefers (say, `Donald E. Knuth'). In the first case, the entries might be alphabetized incorrectly, and in the second, the slightly altered name might foul up somebody's electronic library search. But there's a third possibility, which is the one I prefer. You could convert the second journal's field to
author = "D[onald] E. Knuth"This avoids the pitfalls of the previous two solutions, since
alphabetizes this as if the brackets weren't there, and since the brackets clue the reader in that a full first name was missing from the original. Of course it introduces another pitfall--`D[onald] E. Knuth' looks ugly--but in this case I think the increase in accuracy outweighs the loss in aesthetics.
organization = "The Association for Computing Machinery", key = "ACM"Without the key field, the alpha style would make a label from the first three letters of information in the organization field; alpha knows to strip off the `The ', but it would still form a label like `[Ass86]', which, however intriguing, is uninformative. Including the key field, as above, would yield the better label `[ACM86]'.
You won't always need the key field to override the organization, though: With
organization = "Unilogic, Ltd.",for instance, the alpha style would form the perfectly reasonable label `[Uni86]'.
author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} G{\"o}del"there are just two special characters, `
{\'{E}douard}
'
and `{\"o}
' (the same would be true if the pair of
double quotes delimiting the field were braces instead). In general,
will not do any processing of a TEX or LATEX control sequence inside a special character, but it will process other characters. Thus a style that converts all titles to lower case would convert
The {\TeX BOOK\NOOP} Experienceto
The {\TeX book\NOOP} experience(the `The' is still capitalized because it's the first word of the title).
This special-character scheme is useful for handling accented characters, for getting 's alphabetizing to do what you want, and, since
counts an entire special character as just one letter, for stuffing extra characters inside labels. The file XAMPL.BIB distributed with
gives examples of all three uses.
Each name consists of four parts: First, von, Last, and Jr; each part consists of a (possibly empty) list of name-tokens. The Last part will be nonempty if any part is, so if there's just one token, it's always a Last token.
Recall that Per Brinch Hansen's name should be typed
"Brinch Hansen, Per"The First part of his name has the single token ``Per''; the Last part has two tokens, ``Brinch'' and ``Hansen''; and the von and Jr parts are empty. If you had typed
"Per Brinch Hansen"instead,
would (erroneously) think ``Brinch'' were a First-part token, just as ``Paul'' is a First-part token in ``John Paul Jones'', so this erroneous form would have two First tokens and one Last token.
Here's another example:
"Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"This name has four tokens in the First part, two in the von, and two in the Last. Here
knows where one part ends and the other begins because the tokens in the von part begin with lower-case letters.
In general, it's a von token if the first letter at brace-level 0 is in lower case. Since technically everything in a ``special character'' is at brace-level 0, you can trick
into thinking that a token is or is not a von token by prepending a dummy special character whose first letter past the TEX control sequence is in the desired case, upper or lower.
To summarize,
allows three possible forms for the name:
"First von Last" "von Last, First" "von Last, Jr, First"You may almost always use the first form; you shouldn't if either there's a Jr part, or the Last part has multiple tokens but there's no von part.
This document was generated using the LaTeX2HTML translator Version 2002-1 (1.68)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir15095W9Gc8W/lyx_tmpbuf1/btxdoc.tex
The translation was initiated by root on 2002-12-22