Debian Codegraph @

texmf-dist/doc/bibtex/base/btxdoc.tex

raw
1 % Copyright (C) 1988, 2010 Oren Patashnik.
2 % Unlimited copying and redistribution of this file are permitted if it
3 % is unmodified. Modifications (and their redistribution) are also
4 % permitted, as long as the resulting file is renamed.
5
6 \def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em
7 T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
8
9 \title{B\kern-.05em{\large I}\kern-.025em{\large B}\kern-.08em\TeX ing}
10 \author{Oren Patashnik}
11 \date{February 8, 1988}
12
13 \documentstyle{article}
14 \begin{document}
15
16 \maketitle
17
18 \section{Overview}
19
20 [This document will be expanded when \BibTeX\ version 1.00 comes out.
21 Please report typos, omissions, inaccuracies,
22 and especially unclear explanations
23 to {\tt [email protected]} ({\tt http://lists.tug.org/biblio}).
24 Suggestions for improvements are wanted and welcome.]
25
26 This documentation, for \BibTeX\ version 0.99b,
27 is meant for general \BibTeX\ users;
28 bibliography-style designers should read this document
29 and then read ``Designing \BibTeX\ Styles''~\cite{btxhak},
30 which is meant for just them.
31
32 This document has three parts:
33 Section~\ref{differences}
34 describes the differences between versions 0.98i and 0.99b
35 of \BibTeX\ and between the corresponding versions of the standard styles;
36 Section~\ref{latex-appendix}
37 updates Appendix~B.2 of the \LaTeX\ book~\cite{latex};
38 and Section~\ref{odds-and-ends}
39 gives some general and specific tips
40 that aren't documented elsewhere.
41 It's assumed throughout that you're familiar with
42 the relevant sections of the \LaTeX\ book.
43
44 This documentation also serves as sample input to help
45 \BibTeX\ implementors get it running.
46 For most documents, this one included, you produce the reference list by:
47 running \LaTeX\ on the document (to produce the {\tt aux} file(s)),
48 then running \BibTeX\ (to produce the {\tt bbl} file),
49 then \LaTeX\ twice more (first to find the information in the {\tt bbl} file
50 and then to get the forward references correct).
51 In very rare circumstances you may need an extra \BibTeX/\LaTeX\ run.
52
53 \BibTeX\ version 0.99b should be used with \LaTeX\ version 2.09,
54 for which the closed bibliography format is the default;
55 to get the open format, use the optional document style {\tt openbib}
56 (in an open format there's a line break between major blocks of a
57 reference-list entry; in a closed format the blocks run together).]
58
59 Note: \BibTeX\ 0.99b is not compatible with the old style files;
60 nor is \BibTeX\ 0.98i compatible with the new ones
61 (the new \BibTeX, however, is compatible with old database files).
62
63 Note for implementors: \BibTeX\ provides logical-area names
64 \hbox{\tt TEXINPUTS:} for bibliography-style files and
65 \hbox{\tt TEXBIB:} for database files it can't otherwise find.
66
67
68 \section{Changes}
69 \label{differences}
70
71 This section describes the differences between
72 \BibTeX\ versions 0.98i and 0.99b, and also between
73 the corresponding standard styles.
74 There were a lot of differences;
75 there will be a lot fewer between 0.99 and 1.00.
76
77
78 \subsection{New \BibTeX\ features}
79 \label{features}
80
81 The following list explains \BibTeX's new features and how to use them.
82 \begin{enumerate}
83
84 \item
85 With the single command `\hbox{\verb|\nocite{*}|}'
86 you can now include in the reference list
87 every entry in the database files, without having to explicitly
88 \verb|\cite| or \hbox{\verb|\nocite|} each entry.
89 Giving this command, in essence,
90 \hbox{\verb|\nocite|}s
91 all the enties in the database, in database order,
92 at the very spot in your document
93 where you give the command.
94
95 \item
96 \label{concat}
97 You can now have as a field value (or an {\tt @STRING} definition)
98 the concatenation of several strings.
99 For example if you've defined
100 \begin{verbatim}
101 @STRING( WGA = " World Gnus Almanac" )
102 \end{verbatim}
103 then it's easy to produce nearly-identical
104 {\tt title} fields for different entries:
105 \begin{verbatim}
106 @BOOK(almanac-66,
107 title = 1966 # WGA,
108 . . .
109 @BOOK(almanac-67,
110 title = 1967 # WGA,
111 \end{verbatim}
112 and so on. Or, you could have a field like
113 \begin{verbatim}
114 month = "1~" # jan,
115 \end{verbatim}
116 which would come out something like
117 `\hbox{\verb|1~January|}' or `\hbox{\verb|1~Jan.|}' in the {\tt bbl} file,
118 depending on how your bibliography style defines
119 the {\tt jan} abbreviation.
120 You may concatenate as many strings as you like
121 (except that there's a limit to the overall length
122 of the resulting field);
123 just be sure to put the concatenation character `{\tt\#}'$\!$,
124 surrounded by optional spaces or newlines,
125 between each successive pair of strings.
126
127 \item
128 \BibTeX\ has a new cross-referencing feature,
129 explained by an example.
130 Suppose you say \hbox{\verb|\cite{no-gnats}|} in your document,
131 and suppose you have these two entries in your database file:
132 \begin{verbatim}
133 @INPROCEEDINGS(no-gnats,
134 crossref = "gg-proceedings",
135 author = "Rocky Gneisser",
136 title = "No Gnats Are Taken for Granite",
137 pages = "133-139")
138 . . .
139 @PROCEEDINGS(gg-proceedings,
140 editor = "Gerald Ford and Jimmy Carter",
141 title = "The Gnats and Gnus 1988 Proceedings",
142 booktitle = "The Gnats and Gnus 1988 Proceedings")
143 \end{verbatim}
144 Two things happen.
145 First, the special \hbox{\tt crossref} field tells \BibTeX\
146 that the \hbox{\tt no-gnats} entry should inherit
147 any fields it's missing from
148 the entry it cross references, \hbox{\tt gg-proceedings}.
149 In this case it in inherits the two fields
150 \hbox{\tt editor} and \hbox{\tt booktitle}.
151 Note that, in the standard styles at least,
152 the \hbox{\tt booktitle} field is irrelevant
153 for the \hbox{\tt PROCEEDINGS} entry type.
154 The \hbox{\tt booktitle} field appears here
155 in the \hbox{\tt gg-proceedings} entry
156 only so that the entries that cross reference it
157 may inherit the field.
158 No matter how many papers from this meeting exist in the database,
159 this \hbox{\tt booktitle} field need only appear once.
160
161 The second thing that happens:
162 \BibTeX\ automatically puts the entry \hbox{\tt gg-proceedings}
163 into the reference list if it's cross
164 referenced by two or more entries that you
165 \verb|\cite| or \hbox{\verb|\nocite|},
166 even if you don't \verb|\cite| or \hbox{\verb|\nocite|}
167 the \hbox{\tt gg-proceedings} entry itself.
168 So \hbox{\tt gg-proceedings} will automatically appear
169 on the reference list if one other entry
170 besides \hbox{\tt no-gnats} cross references it.
171
172 To guarantee that this scheme works, however,
173 a cross-referenced entry must occur later in the database files
174 than every entry that cross-references it.
175 Thus, putting all cross-referenced entries at the end makes sense.
176 (Moreover, you may not reliably nest cross references;
177 that is, a cross-referenced entry may
178 not itself reliably cross reference an entry.
179 This is almost certainly not something you'd
180 want to do, though.)
181
182 One final note:
183 This cross-referencing feature is completely unrelated
184 to the old \BibTeX's cross referencing,
185 which is still allowed.
186 Thus, having a field like
187 \begin{verbatim}
188 note = "Jones \cite{jones-proof} improves the result"
189 \end{verbatim}
190 is not affected by the new feature.
191
192 \item
193 \BibTeX\ now handles accented characters.
194 For example if you have an entry with the two fields
195 \begin{verbatim}
196 author = "Kurt G{\"o}del",
197 year = 1931,
198 \end{verbatim}
199 and if you're using the \hbox{\tt alpha} bibliography style,
200 then \BibTeX\ will construct the label
201 \hbox{[G{\"o}d31]} for this entry, which is what you'd want.
202 To get this feature to work you must place the entire accented
203 character in braces;
204 in this case either \hbox{\verb|{\"o}|}
205 or \hbox{\verb|{\"{o}}|} will do.
206 Furthermore these braces must not themselves be
207 enclosed in braces (other than the ones that might delimit
208 the entire field or the entire entry);
209 and there must be a backslash
210 as the very first character inside the braces.
211 Thus neither \hbox{\verb|{G{\"{o}}del}|}
212 nor \hbox{\verb|{G\"{o}del}|} will work for this example.
213
214 This feature handles all the accented characters and
215 all but the nonbackslashed foreign symbols found in Tables
216 3.1 and~3.2 of the \LaTeX\ book.
217 This feature behaves similarly for ``accents'' you might define;
218 we'll see an example shortly.
219 For the purposes of counting letters in labels,
220 \BibTeX\ considers everything contained inside the braces
221 as a single letter.
222
223 \item
224 \BibTeX\ also handles hyphenated names.
225 For example if you have an entry with
226 \begin{verbatim}
227 author = "Jean-Paul Sartre",
228 \end{verbatim}
229 and if you're using the \hbox{\tt abbrv} style,
230 then the result is `J.-P. Sartre'$\!$.
231
232 \item
233 \label{preamble}
234 There's now an \hbox{\verb|@PREAMBLE|} command
235 for the database files.
236 This command's syntax is just like \hbox{\verb|@STRING|}'s,
237 except that there is no name or equals-sign, just the string.
238 Here's an example:
239 \begin{verbatim}
240 @PREAMBLE{ "\newcommand{\noopsort}[1]{} "
241 # "\newcommand{\singleletter}[1]{#1} " }
242 \end{verbatim}
243 (note the use of concatenation here, too).
244 The standard styles output whatever information you give this command
245 (\LaTeX\ macros most likely) directly to the {\tt bbl} file.
246 We'll look at one possible use of this command,
247 based on the \hbox{\verb|\noopsort|} command just defined.
248
249 The issue here is sorting (alphabetizing).
250 \BibTeX\ does a pretty good job,
251 but occasionally weird circumstances conspire to confuse \BibTeX:
252 Suppose that you have entries in your database for
253 the two books in a two-volume set by the same author,
254 and that you'd like volume~1 to appear
255 just before volume~2 in your reference list.
256 Further suppose that there's now a second edition of volume~1,
257 which came out in 1973, say,
258 but that there's still just one edition of volume~2,
259 which came out in 1971.
260 Since the {\tt plain} standard style
261 sorts by author and then year,
262 it will place volume~2 first
263 (because its edition came out two years earlier)
264 unless you help \BibTeX.
265 You can do this by using the {\tt year} fields below
266 for the two volumes:
267 \begin{verbatim}
268 year = "{\noopsort{a}}1973"
269 . . .
270 year = "{\noopsort{b}}1971"
271 \end{verbatim}
272 According to the definition of \hbox{\verb|\noopsort|},
273 \LaTeX\ will print nothing but the true year for these fields.
274 But \BibTeX\ will be perfectly happy pretending that
275 \hbox{\verb|\noopsort|} specifies some fancy accent
276 that's supposed to adorn the `a' and the~`b';
277 thus when \BibTeX\ sorts it will pretend that
278 `a1973' and `b1971' are the real years,
279 and since `a' comes before~`b'$\!$, it will place volume~1 before volume~2,
280 just what you wanted.
281 By the way, if this author has any other works included
282 in your database, you'd probably want to use instead something like
283 \hbox{\verb|{\noopsort{1968a}}1973|} and
284 \hbox{\verb|{\noopsort{1968b}}1971|},
285 so that these two books would come out in a reasonable spot
286 relative to the author's other works
287 (this assumes that 1968 results in a reasonable spot,
288 say because that's when the first edition of volume~1 appeared).
289
290 There is a limit to the number of \hbox{\verb|@PREAMBLE|} commands
291 you may use, but you'll never exceed this limit if
292 you restrict yourself to one per database file;
293 this is not a serious restriction,
294 given the concatenation feature (item~\ref{concat}).
295
296 \item
297 \BibTeX's sorting algorithm is now stable.
298 This means that if two entries have identical sort keys,
299 those two entries will appear in citation order.
300 (The bibliography styles construct these sort keys---%
301 usually the author information followed by the year and the title.)
302
303 \item
304 \BibTeX\ no longer does case conversion for file names;
305 this will make \BibTeX\ easier to install on Unix systems, for example.
306
307 \item
308 It's now easier to add code for processing a
309 command-line {\tt aux}-file name.
310
311 \end{enumerate}
312
313
314 \subsection{Changes to the standard styles}
315
316 This section describes changes to the standard styles
317 ({\tt plain}, {\tt unsrt}, {\tt alpha}, {\tt abbrv})
318 that affect ordinary users.
319 Changes that affect style designers appear in
320 the document ``Designing \BibTeX\ Styles''~\cite{btxhak}.
321 \begin{enumerate}
322
323 \item
324 In general, sorting is now by ``author''$\!$, then year, then title---%
325 the old versions didn't use the year field.
326 (The {\tt alpha} style, however, sorts first by label,
327 then ``author''$\!$, year, and title.)
328 The quotes around author mean that some entry types
329 might use something besides the author, like the editor or organization.
330
331 \item
332 Many unnecessary ties (\verb|~|) have been removed.
333 \LaTeX\ thus will produce slightly fewer
334 `\hbox{\tt Underfull} \verb|\hbox|' messages
335 when it's formatting the reference list.
336
337 \item
338 Emphasizing (\hbox{\verb|{\em ...}|})
339 has replaced italicizing (\hbox{\verb|{\it ...}|}).
340 This will almost never result in a difference
341 between the old output and the new.
342
343 \item
344 The {\tt alpha} style now uses a superscripted~`$^{+}$' instead of a~`*'
345 to represent names omitted in constructing the label.
346 If you really liked it the way it was, however,
347 or if you want to omit the character entirely,
348 you don't have to modify the style file---%
349 you can override the~`$^{+}$' by
350 redefining the \hbox{\verb|\etalchar|} command
351 that the {\tt alpha} style writes onto the {\tt bbl} file
352 (just preceding the \hbox{\verb|\thebibliography|} environment);
353 use \LaTeX's \hbox{\verb|\renewcommand|} inside
354 a database \hbox{\tt @PREAMBLE} command,
355 described in the previous subsection's item~\ref{preamble}.
356
357 \item
358 The {\tt abbrv} style now uses `Mar.' and `Sept.'\
359 for those months rather than `March' and `Sep.'
360
361 \item
362 The standard styles use \BibTeX's new cross-referencing feature
363 by giving a \verb|\cite| of the cross-referenced entry and by
364 omitting from the cross-referencing entry
365 (most of the) information that appears
366 in the cross-referenced entry.
367 These styles do this when
368 a titled thing (the cross-referencing entry)
369 is part of a larger titled thing (the cross-referenced entry).
370 There are five such situations:
371 when (1)~an \hbox{\tt INPROCEEDINGS}
372 (or \hbox{\tt CONFERENCE}, which is the same)
373 cross references a \hbox{\tt PROCEEDINGS};
374 when (2)~a {\tt BOOK}, (3)~an \hbox{\tt INBOOK},
375 or (4)~an \hbox{\tt INCOLLECTION}
376 cross references a {\tt BOOK}
377 (in these cases, the cross-referencing entry is a single
378 volume in a multi-volume work);
379 and when (5)~an \hbox{\tt ARTICLE}
380 cross references an \hbox{\tt ARTICLE}
381 (in this case, the cross-referenced entry is really a journal,
382 but there's no \hbox{\tt JOURNAL} entry type;
383 this will result in warning messages about
384 an empty \hbox{\tt author} and \hbox{\tt title} for the journal---%
385 you should just ignore these warnings).
386
387 \item
388 The \hbox{\tt MASTERSTHESIS} and \hbox{\tt PHDTHESIS}
389 entry types now take an optional {\tt type} field.
390 For example you can get the standard styles to
391 call your reference a `Ph.D.\ dissertation'
392 instead of the default `PhD thesis' by including a
393 \begin{verbatim}
394 type = "{Ph.D.} dissertation"
395 \end{verbatim}
396 in your database entry.
397
398 \item
399 Similarly, the \hbox{\tt INBOOK} and \hbox{\tt INCOLLECTION}
400 entry types now take an optional {\tt type} field,
401 allowing `section~1.2' instead of the default `chapter~1.2'$\!$.
402 You get this by putting
403 \begin{verbatim}
404 chapter = "1.2",
405 type = "Section"
406 \end{verbatim}
407 in your database entry.
408
409 \item
410 The \hbox{\tt BOOKLET}, \hbox{\tt MASTERSTHESIS},
411 and \hbox{\tt TECHREPORT} entry types now format
412 their \hbox{\tt title} fields as if they were
413 \hbox{\tt ARTICLE} \hbox{\tt title}s
414 rather than \hbox{\tt BOOK} \hbox{\tt title}s.
415
416 \item
417 The \hbox{\tt PROCEEDINGS} and \hbox{\tt INPROCEEDINGS}
418 entry types now use the \hbox{\tt address} field
419 to tell where a conference was held,
420 rather than to give the address
421 of the publisher or organization.
422 If you want to include the
423 publisher's or organization's address,
424 put it in the \hbox{\tt publisher}
425 or \hbox{\tt organization} field.
426
427 \item
428 The \hbox{\tt BOOK}, \hbox{\tt INBOOK}, \hbox{\tt INCOLLECTION},
429 and \hbox{\tt PROCEEDINGS} entry types now allow either
430 \hbox{\tt volume} or \hbox{\tt number} (but not both),
431 rather than just \hbox{\tt volume}.
432
433 \item
434 The \hbox{\tt INCOLLECTION} entry type now allows
435 a \hbox{\tt series} and an \hbox{\tt edition} field.
436
437 \item
438 The \hbox{\tt INPROCEEDINGS} and \hbox{\tt PROCEEDINGS}
439 entry types now allow either a \hbox{\tt volume} or \hbox{\tt number},
440 and also a \hbox{\tt series} field.
441
442 \item
443 The \hbox{\tt UNPUBLISHED} entry type now outputs,
444 in one block, the \hbox{\tt note} field
445 followed by the date information.
446
447 \item
448 The \hbox{\tt MANUAL} entry type now prints out
449 the \hbox{\tt organization} in the first block
450 if the \hbox{\tt author} field is empty.
451
452 \item
453 The {\tt MISC} entry type now issues a warning
454 if all the optional fields are empty
455 (that is, if the entire entry is empty).
456
457 \end{enumerate}
458
459
460 \section{The Entries}
461 \label{latex-appendix}
462
463 This section is simply a corrected version of
464 Appendix~B.2 of the \LaTeX\ book~\cite{latex},
465 \copyright~1986, by Addison-Wesley.
466 The basic scheme is the same, only a few details have changed.
467
468
469 \subsection{Entry Types}
470
471 When entering a reference in the database, the first thing to decide
472 is what type of entry it is. No fixed classification scheme can be
473 complete, but \BibTeX\ provides enough entry types to handle almost
474 any reference reasonably well.
475
476 References to different types of publications contain different
477 information; a reference to a journal article might include the volume
478 and number of the journal, which is usually not meaningful for a book.
479 Therefore, database entries of different types have different fields.
480 For each entry type, the fields are divided into three classes:
481 \begin{description}
482
483 \item[required]
484 Omitting the field will produce a warning message
485 and, rarely, a badly formatted bibliography entry.
486 If the required information is not meaningful,
487 you are using the wrong entry type.
488 However, if the required information is meaningful
489 but, say, already included is some other field,
490 simply ignore the warning.
491
492 \item[optional]
493 The field's information will be used if present,
494 but can be omitted without causing any formatting problems.
495 You should include the optional field if it will help the reader.
496
497 \item[ignored]
498 The field is ignored.
499 \BibTeX\ ignores any field that is not required or optional, so you can include
500 any fields you want in a \hbox{\tt bib} file entry. It's a good idea
501 to put all relevant information about
502 a reference in its \hbox{\tt bib} file entry---even information that
503 may never appear in the bibliography. For example, if you want to
504 keep an abstract of a paper in a computer file, put it in an \hbox{\tt
505 abstract} field in the paper's \hbox{\tt bib} file entry. The
506 \hbox{\tt bib} file is likely to be as good a place as any for the
507 abstract, and it is possible to design a bibliography style for
508 printing selected abstracts.
509 Note: Misspelling a field name will
510 result in its being ignored,
511 so watch out for typos
512 (especially for optional fields,
513 since \BibTeX\ won't warn you when those are missing).
514
515 \end{description}
516
517 The following are the standard entry types, along with their required
518 and optional fields, that are used by the standard bibliography styles.
519 The fields within each class (required or optional)
520 are listed in order of occurrence in the output,
521 except that a few entry types may perturb the order slightly,
522 depending on what fields are missing.
523 These entry types are similar to those adapted by Brian Reid
524 from the classification scheme of van~Leunen~\cite{van-leunen}
525 for use in the {\em Scribe\/} system.
526 The meanings of the individual fields are explained in the next section.
527 Some nonstandard bibliography styles may ignore some optional fields
528 in creating the reference.
529 Remember that, when used in the \hbox{\tt bib}
530 file, the entry-type name is preceded by an \hbox{\tt @} character.
531
532 \begin{description}
533 \sloppy
534
535 \item[article\hfill] An article from a journal or magazine.
536 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt journal},
537 \hbox{\tt year}.
538 Optional fields: \hbox{\tt volume}, \hbox{\tt number},
539 \hbox{\tt pages}, \hbox{\tt month}, \hbox{\tt note}.
540
541 \item[book\hfill] A book with an explicit publisher.
542 Required fields: \hbox{\tt author} or \hbox{\tt editor},
543 \hbox{\tt title}, \hbox{\tt publisher}, \hbox{\tt year}.
544 Optional fields: \hbox{\tt volume} or \hbox{\tt number}, \hbox{\tt series},
545 \hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month},
546 \hbox{\tt note}.
547
548 \item[booklet\hfill] A work that is printed and bound,
549 but without a named publisher or sponsoring institution.
550 Required field: \hbox{\tt title}.
551 Optional fields: \hbox{\tt author}, \hbox{\tt howpublished},
552 \hbox{\tt address}, \hbox{\tt month}, \hbox{\tt year}, \hbox{\tt note}.
553
554 \item[conference\hfill] The same as {\tt INPROCEEDINGS},
555 included for {\em Scribe\/} compatibility.
556
557 \item[inbook\hfill] A part of a book,
558 which may be a chapter (or section or whatever) and/or a range of pages.
559 Required fields: \hbox{\tt author} or \hbox{\tt editor}, \hbox{\tt title},
560 \hbox{\tt chapter} and/or \hbox{\tt pages}, \hbox{\tt publisher},
561 \hbox{\tt year}.
562 Optional fields: \hbox{\tt volume} or \hbox{\tt number}, \hbox{\tt series},
563 \hbox{\tt type}, \hbox{\tt address},
564 \hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt note}.
565
566 \item[incollection\hfill] A part of a book having its own title.
567 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt booktitle},
568 \hbox{\tt publisher}, \hbox{\tt year}.
569 Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number},
570 \hbox{\tt series}, \hbox{\tt type}, \hbox{\tt chapter}, \hbox{\tt pages},
571 \hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt note}.
572
573 \item[inproceedings\hfill] An article in a conference proceedings.
574 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt booktitle},
575 \hbox{\tt year}.
576 Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number},
577 \hbox{\tt series}, \hbox{\tt pages}, \hbox{\tt address}, \hbox{\tt month},
578 \hbox{\tt organization}, \hbox{\tt publisher}, \hbox{\tt note}.
579
580 \item[manual\hfill] Technical documentation. Required field: \hbox{\tt title}.
581 Optional fields: \hbox{\tt author}, \hbox{\tt organization},
582 \hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt year},
583 \hbox{\tt note}.
584
585 \item[mastersthesis\hfill] A Master's thesis.
586 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt school},
587 \hbox{\tt year}.
588 Optional fields: \hbox{\tt type}, \hbox{\tt address}, \hbox{\tt month},
589 \hbox{\tt note}.
590
591 \item[misc\hfill] Use this type when nothing else fits.
592 Required fields: none.
593 Optional fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt howpublished},
594 \hbox{\tt month}, \hbox{\tt year}, \hbox{\tt note}.
595
596 \item[phdthesis\hfill] A PhD thesis.
597 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt school},
598 \hbox{\tt year}.
599 Optional fields: \hbox{\tt type}, \hbox{\tt address}, \hbox{\tt month},
600 \hbox{\tt note}.
601
602 \item[proceedings\hfill] The proceedings of a conference.
603 Required fields: \hbox{\tt title}, \hbox{\tt year}.
604 Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number},
605 \hbox{\tt series}, \hbox{\tt address}, \hbox{\tt month},
606 \hbox{\tt organization}, \hbox{\tt publisher}, \hbox{\tt note}.
607
608
609 \item[techreport\hfill] A report published by a school or other institution,
610 usually numbered within a series.
611 Required fields: \hbox{\tt author},
612 \hbox{\tt title}, \hbox{\tt institution}, \hbox{\tt year}.
613 Optional fields: \hbox{\tt type}, \hbox{\tt number}, \hbox{\tt address},
614 \hbox{\tt month}, \hbox{\tt note}.
615
616 \item[unpublished\hfill] A document having an author and title,
617 but not formally published.
618 Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt note}.
619 Optional fields: \hbox{\tt month}, \hbox{\tt year}.
620
621 \end{description}
622
623 In addition to the fields listed above, each entry type also has an
624 optional \hbox{\tt key} field, used in some styles
625 for alphabetizing, for cross referencing,
626 or for forming a \hbox{\verb|\bibitem|} label.
627 You should include a \hbox{\tt key} field for any entry whose
628 ``author'' information is missing;
629 the ``author'' information is usually the \hbox{\tt author} field,
630 but for some entry types it can be the \hbox{\tt editor}
631 or even the \hbox{\tt organization} field
632 (Section~\ref{odds-and-ends} describes this in more detail).
633 Do not confuse the \hbox{\tt key} field with the key that appears in the
634 \hbox{\verb|\cite|} command and at the beginning of the database entry;
635 this field is named ``key'' only for compatibility with {\it Scribe}.
636
637
638 \subsection{Fields}
639
640 Below is a description of all fields
641 recognized by the standard bibliography styles.
642 An entry can also contain other fields, which are ignored by those styles.
643 \begin{description}
644
645 \item[address\hfill]
646 Usually the address of the \hbox{\tt publisher} or other type
647 of institution.
648 For major publishing houses,
649 van~Leunen recommends omitting the information entirely.
650 For small publishers, on the other hand, you can help the
651 reader by giving the complete address.
652
653 \item[annote\hfill]
654 An annotation.
655 It is not used by the standard bibliography styles,
656 but may be used by others that produce an annotated bibliography.
657
658 \item[author\hfill]
659 The name(s) of the author(s),
660 in the format described in the \LaTeX\ book.
661
662 \item[booktitle\hfill]
663 Title of a book, part of which is being cited.
664 See the \LaTeX\ book for how to type titles.
665 For book entries, use the \hbox{\tt title} field instead.
666
667 \item[chapter\hfill]
668 A chapter (or section or whatever) number.
669
670 \item[crossref\hfill]
671 The database key of the entry being cross referenced.
672
673 \item[edition\hfill]
674 The edition of a book---for example, ``Second''$\!$.
675 This should be an ordinal, and
676 should have the first letter capitalized, as shown here;
677 the standard styles convert to lower case when necessary.
678
679 \item[editor\hfill]
680 Name(s) of editor(s), typed as indicated in the \LaTeX\ book.
681 If there is also an \hbox{\tt author} field, then
682 the \hbox{\tt editor} field gives the editor of the book or collection
683 in which the reference appears.
684
685 \item[howpublished\hfill]
686 How something strange has been published.
687 The first word should be capitalized.
688
689 \item[institution\hfill]
690 The sponsoring institution of a technical report.
691
692 \item[journal\hfill]
693 A journal name.
694 Abbreviations are provided for many journals; see the {\it Local Guide}.
695
696 \item[key\hfill]
697 Used for alphabetizing, cross referencing, and creating a label when
698 the ``author'' information
699 (described in Section~\ref{odds-and-ends}) is missing.
700 This field should not be confused with the key that appears in the
701 \hbox{\verb|\cite|} command and at the beginning of the database entry.
702
703 \item[month\hfill]
704 The month in which the work was
705 published or, for an unpublished work, in which it was written.
706 You should use the standard three-letter abbreviation,
707 as described in Appendix B.1.3 of the \LaTeX\ book.
708
709 \item[note\hfill]
710 Any additional information that can help the reader.
711 The first word should be capitalized.
712
713 \item[number\hfill]
714 The number of a journal, magazine, technical report,
715 or of a work in a series.
716 An issue of a journal or magazine is usually
717 identified by its volume and number;
718 the organization that issues a
719 technical report usually gives it a number;
720 and sometimes books are given numbers in a named series.
721
722 \item[organization\hfill]
723 The organization that sponsors a conference or that publishes a \hbox{manual}.
724
725 \item[pages\hfill]
726 One or more page numbers or range of numbers,
727 such as \hbox{\tt 42--111} or \hbox{\tt 7,41,73--97} or \hbox{\tt 43+}
728 (the `{\tt +}' in this last example indicates pages following
729 that don't form a simple range).
730 To make it easier to maintain {\em Scribe\/}-compatible databases,
731 the standard styles convert a single dash (as in \hbox{\tt 7-33})
732 to the double dash used in \TeX\ to denote number ranges
733 (as in \hbox{\tt 7--33}).
734
735 \item[publisher\hfill]
736 The publisher's name.
737
738 \item[school\hfill]
739 The name of the school where a thesis was written.
740
741 \item[series\hfill]
742 The name of a series or set of books.
743 When citing an entire book, the the \hbox{\tt title} field
744 gives its title and an optional \hbox{\tt series} field gives the
745 name of a series or multi-volume set
746 in which the book is published.
747
748 \item[title\hfill]
749 The work's title, typed as explained in the \LaTeX\ book.
750
751 \item[type\hfill]
752 The type of a technical report---for example,
753 ``Research Note''$\!$.
754
755 \item[volume\hfill]
756 The volume of a journal or multivolume book.
757
758 \item[year\hfill]
759 The year of publication or, for
760 an unpublished work, the year it was written.
761 Generally it should consist of four numerals, such as {\tt 1984},
762 although the standard styles can handle any {\tt year} whose
763 last four nonpunctuation characters are numerals,
764 such as `\hbox{(about 1984)}'$\!$.
765
766 \end{description}
767
768
769 \section{Helpful Hints}
770 \label{odds-and-ends}
771
772 This section gives some random tips
773 that aren't documented elsewhere,
774 at least not in this detail.
775 They are, roughly, in order
776 of least esoteric to most.
777 First, however, a brief spiel.
778
779 I understand that there's often little choice in choosing
780 a bibliography style---journal~$X$ says you must use style~$Y$
781 and that's that.
782 If you have a choice, however, I strongly recommend that you
783 choose something like the {\tt plain} standard style.
784 Such a style, van~Leunen~\cite{van-leunen} argues convincingly,
785 encourages better writing than the alternatives---%
786 more concrete, more vivid.
787
788 {\em The Chicago Manual of Style\/}~\cite{chicago},
789 on the other hand,
790 espouse the author-date system,
791 in which the citation might appear in the text as `(Jones, 1986)'$\!$.
792 I argue that this system,
793 besides cluttering up the
794 text with information that may or may not be relevant,
795 encourages the passive voice and vague writing.
796 Furthermore the strongest arguments for
797 using the author-date system---like ``it's the most practical''---%
798 fall flat on their face with the advent
799 of computer-typesetting technology.
800 For instance the {\em Chicago Manual\/} contains,
801 right in the middle of page~401, this anachronism:
802 ``The chief disadvantage of [a style like {\tt plain}] is that additions
803 or deletions cannot be made after the manuscript is typed without changing
804 numbers in both text references and list.''
805 \LaTeX, obviously, sidesteps the disadvantage.
806
807 Finally, the logical deficiencies of the author-date style
808 are quite evident once you've written a program to implement it.
809 For example, in a large bibliography,
810 using the standard alphabetizing scheme,
811 the entry for `(Aho et~al., 1983b)'
812 might be half a page later than the one for `(Aho et~al., 1983a)'$\!$.
813 Fixing this problem results in even worse ones.
814 What a mess.
815 (I have, unfortunately, programmed such a style,
816 and if you're saddled with an unenlightened publisher
817 or if you don't buy my propaganda,
818 it's available from the Rochester style collection.)
819
820 Ok, so the spiel wasn't very brief;
821 but it made me feel better,
822 and now my blood pressure is back to normal.
823 Here are the tips for using \BibTeX\
824 with the standard styles
825 (although many of them hold for nonstandard styles, too).
826 \begin{enumerate}
827
828 \item
829 With \BibTeX's style-designing language
830 you can program general database manipulations,
831 in addition to bibliography styles.
832 For example it's a fairly easy task for someone familiar with the language
833 to produce a database-key/author index of all the entries in a database.
834 Consult the {\em Local Guide\/} to see
835 what tools are available on your system.
836
837 \item
838 The standard style's thirteen entry types
839 do reasonably well at formatting most entries,
840 but no scheme with just thirteen formats
841 can do everything perfectly.
842 Thus, you should feel free to be creative
843 in how you use these entry types
844 (but if you have to be too creative,
845 there's a good chance you're using the wrong entry type).
846
847 \item
848 Don't take the field names too seriously.
849 Sometimes, for instance, you might have to include
850 the publisher's address along with the publisher's name
851 in the \hbox{\tt publisher} field,
852 rather than putting it in the \hbox{\tt address} field.
853 Or sometimes, difficult entries work best when you
854 make judicious use of the {\tt note} field.
855
856 \item
857 Don't take the warning messages too seriously.
858 Sometimes, for instance, the year appears in the title,
859 as in {\em The 1966 World Gnus Almanac}.
860 In this case it's best to omit the {\tt year} field
861 and to ignore \BibTeX's warning message.
862
863 \item
864 If you have too many names to list in an
865 \hbox{\tt author} or \hbox{\tt editor} field,
866 you can end the list with ``and others'';
867 the standard styles appropriately append an ``et~al.''
868
869 \item
870 In general, if you want to keep \BibTeX\ from changing
871 something to lower case, you enclose it in braces.
872 You might not get the effect you want, however,
873 if the very first character after the left brace is a backslash.
874 The ``special characters'' item later in this section explains.
875
876 \item
877 For {\em Scribe\/} compatibility, the database files
878 allow an \hbox{\tt @COMMENT} command; it's not really
879 needed because \BibTeX\ allows in the database files
880 any comment that's not within an entry.
881 If you want to comment out an entry,
882 simply remove the `{\tt @}' character preceding the entry type.
883
884 \item
885 The standard styles have journal abbreviations that are
886 computer-science oriented;
887 these are in the style files primarily for the example.
888 If you have a different set of journal abbreviations,
889 it's sensible to put them in \hbox{\tt @STRING} commands
890 in their own database file and to list this database file
891 as an argument to \LaTeX's \hbox{\verb|\bibliography|} command
892 (but you should list this argument before the ones that
893 specify real database entries).
894
895 \item
896 It's best to use the three-letter abbreviations for the month,
897 rather than spelling out the month yourself.
898 This lets the bibliography style be consistent.
899 And if you want to include information for the day of the month,
900 the {\tt month} field is usually the best place.
901 For example
902 \begin{verbatim}
903 month = jul # "~4,"
904 \end{verbatim}
905 will probably produce just what you want.
906
907 \item
908 If you're using the \hbox{\tt unsrt} style
909 (references are listed in order of citation)
910 along with the \hbox{\verb|\nocite{*}|} feature
911 (all entries in the database are included),
912 the placement of the \hbox{\verb|\nocite{*}|} command
913 within your document file will determine the reference order.
914 According to the rule given in Section~\ref{features}:
915 If the command is placed at the beginning of the document,
916 the entries will be listed in exactly the order
917 they occur in the database;
918 if it's placed at the end,
919 the entries that you explicitly
920 \hbox{\verb|\cite|} or \hbox{\verb|\nocite|}
921 will occur in citation order,
922 and the remaining database entries will be in database order.
923
924 \item
925 For theses, van Leunen recommends not giving
926 the school's department after the name of the degree,
927 since schools, not departments, issue degrees.
928 If you really think that giving the department information
929 will help the reader find the thesis,
930 put that information in the \hbox{\tt address} field.
931
932 \item
933 The \hbox{\tt MASTERSTHESIS} and \hbox{\tt PHDTHESIS} entry types
934 are so named for {\em Scribe\/} compatibility;
935 \hbox{\tt MINORTHESIS} and \hbox{\tt MAJORTHESIS}
936 probably would have been better names.
937 Keep this in mind when trying to classify
938 a non-U.S.\ thesis.
939
940 \item
941 Here's yet another suggestion for what to do when an author's
942 name appears slightly differently in two publications.
943 Suppose, for example, two journals articles use these fields.
944 \begin{verbatim}
945 author = "Donald E. Knuth"
946 . . .
947 author = "D. E. Knuth"
948 \end{verbatim}
949 There are two possibilities.
950 You could (1)~simply leave them as is,
951 or (2)~assuming you know for sure that
952 these authors are one and the same person,
953 you could list both in the form that the author prefers
954 (say, `Donald~E.\ Knuth').
955 In the first case, the entries might be alphabetized incorrectly,
956 and in the second, the slightly altered name might
957 foul up somebody's electronic library search.
958 But there's a third possibility, which is the one I prefer.
959 You could convert the second journal's field to
960 \begin{verbatim}
961 author = "D[onald] E. Knuth"
962 \end{verbatim}
963 This avoids the pitfalls of the previous two solutions,
964 since \BibTeX\ alphabetizes this as if the brackets weren't there,
965 and since the brackets clue the reader in that a full first name
966 was missing from the original.
967 Of course it introduces another pitfall---`D[onald]~E.\ Knuth' looks ugly---%
968 but in this case I think the increase in accuracy outweighs
969 the loss in aesthetics.
970
971 \item
972 \LaTeX's comment character `{\tt\%}' is not a comment character
973 in the database files.
974
975 \item
976 Here's a more complete description of
977 the ``author'' information referred to in previous sections.
978 For most entry types the ``author'' information
979 is simply the \hbox{\tt author} field.
980 However:
981 For the \hbox{\tt BOOK} and \hbox{\tt INBOOK} entry types
982 it's the \hbox{\tt author} field, but if there's no author
983 then it's the \hbox{\tt editor} field;
984 for the \hbox{\tt MANUAL} entry type
985 it's the \hbox{\tt author} field, but if there's no author
986 then it's the \hbox{\tt organization} field;
987 and for the \hbox{\tt PROCEEDINGS} entry type
988 it's the \hbox{\tt editor} field, but if there's no editor
989 then it's the \hbox{\tt organization} field.
990
991 \item
992 When creating a label,
993 the \hbox{\tt alpha} style uses the ``author'' information described above,
994 but with a slight change---%
995 for the \hbox{\tt MANUAL} and \hbox{\tt PROCEEDINGS} entry types,
996 the {\tt key} field takes precedence over the \hbox{\tt organization} field.
997 Here's a situation where this is useful.
998 \begin{verbatim}
999 organization = "The Association for Computing Machinery",
1000 key = "ACM"
1001 \end{verbatim}
1002 Without the {\tt key} field, the \hbox{\tt alpha} style
1003 would make a label from the first three letters of information
1004 in the \hbox{\tt organization} field;
1005 \hbox{\tt alpha} knows to strip off the `\hbox{\tt The }'$\!$,
1006 but it would still form a label like `\hbox{[Ass86]}'$\!$,
1007 which, however intriguing, is uninformative.
1008 Including the {\tt key} field, as above,
1009 would yield the better label `\hbox{[ACM86]}'$\!$.
1010
1011 You won't always need the {\tt key} field to override the
1012 \hbox{\tt organization}, though:
1013 With
1014 \begin{verbatim}
1015 organization = "Unilogic, Ltd.",
1016 \end{verbatim}
1017 for instance, the \hbox{\tt alpha} style would
1018 form the perfectly reasonable label `\hbox{[Uni86]}'$\!$.
1019
1020 \item
1021 Section~\ref{features} discusses accented characters.
1022 To \BibTeX, an accented character is really a special case
1023 of a ``special character''$\!$,
1024 which consists of everything from a left brace at the top-most level,
1025 immediately followed by a backslash,
1026 up through the matching right brace.
1027 For example in the field
1028 \begin{verbatim}
1029 author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} G{\"o}del"
1030 \end{verbatim}
1031 there are just two special characters,
1032 `\hbox{\verb|{\'{E}douard}|}' and `\hbox{\verb|{\"o}|}'
1033 (the same would be true if the pair of double quotes
1034 delimiting the field were braces instead).
1035 In general, \BibTeX\ will not do any processing
1036 of a \TeX\ or \LaTeX\ control sequence inside a special character,
1037 but it {\em will\/} process other characters.
1038 Thus a style that converts all titles to lower case
1039 would convert
1040 \begin{verbatim}
1041 The {\TeX BOOK\NOOP} Experience
1042 \end{verbatim}
1043 to
1044 \begin{verbatim}
1045 The {\TeX book\NOOP} experience
1046 \end{verbatim}
1047 (the `{\tt The}' is still capitalized
1048 because it's the first word of the title).
1049
1050 This special-character scheme is useful for handling accented characters,
1051 for getting \BibTeX's alphabetizing to do what you want,
1052 and, since \BibTeX\ counts an entire special character as just one letter,
1053 for stuffing extra characters inside labels.
1054 The file \hbox{\tt XAMPL.BIB} distributed with \BibTeX\
1055 gives examples of all three uses.
1056
1057 \item
1058 This final item of the section describes \BibTeX's names
1059 (which appear in the \hbox{\tt author} or \hbox{\tt editor} field)
1060 in slightly more detail than what
1061 appears in Appendix~B of the \LaTeX\ book.
1062 In what follows, a ``name'' corresponds to a person.
1063 (Recall that you separate multiple names in a single field
1064 with the word ``and''$\!$, surrounded by spaces,
1065 and not enclosed in braces.
1066 This item concerns itself with the structure of a single name.)
1067
1068 Each name consists of four parts: First, von, Last, and~Jr;
1069 each part consists of a (possibly empty) list of name-tokens.
1070 The Last part will be nonempty if any part is,
1071 so if there's just one token, it's always a Last token.
1072
1073 Recall that Per Brinch~Hansen's name should be typed
1074 \begin{verbatim}
1075 "Brinch Hansen, Per"
1076 \end{verbatim}
1077 The First part of his name has the single token ``Per'';
1078 the Last part has two tokens, ``Brinch'' and ``Hansen'';
1079 and the von and Jr parts are empty.
1080 If you had typed
1081 \begin{verbatim}
1082 "Per Brinch Hansen"
1083 \end{verbatim}
1084 instead, \BibTeX\ would (erroneously) think ``Brinch'' were a First-part token,
1085 just as ``Paul'' is a First-part token in ``John~Paul Jones''$\!$,
1086 so this erroneous form would have two First tokens and one Last token.
1087
1088 Here's another example:
1089 \begin{verbatim}
1090 "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"
1091 \end{verbatim}
1092 This name has four tokens in the First part, two in the von, and
1093 two in the Last.
1094 Here \BibTeX\ knows where one part ends and the other begins because
1095 the tokens in the von part begin with lower-case letters.
1096
1097 In general, it's a von token if the first letter at brace-level~0
1098 is in lower case.
1099 Since technically everything
1100 in a ``special character'' is at brace-level~0,
1101 you can trick \BibTeX\ into thinking that
1102 a token is or is not a von token by prepending a dummy
1103 special character whose first letter past the \TeX\ control sequence
1104 is in the desired case, upper or lower.
1105
1106 To summarize, \BibTeX\ allows three possible forms for the name:
1107 \begin{verbatim}
1108 "First von Last"
1109 "von Last, First"
1110 "von Last, Jr, First"
1111 \end{verbatim}
1112 You may almost always use the first form;
1113 you shouldn't if either there's a Jr part,
1114 or the Last part has multiple tokens but there's no von part.
1115
1116 \end{enumerate}
1117
1118 \bibliography{btxdoc}
1119 \bibliographystyle{plain}
1120 \end{document}