Chapter 12. Managing Citations

There are numerous ways to compile bibliographies and reference lists. They can be prepared manually, if necessary, but usually they are automatically generated from a database containing bibliographic information (see Chapter 13). This chapter introduces some of the many presentation forms of bibliographical sources and it reviews different traditions regarding how such sources are referred to in a document.

The chapter begins with a short introduction to the major citation schemes in common use. This is followed by a description of LaTeX’s standard markup for bibliography lists and its interface to the BibTeX program that can be used to produce such lists automatically from a (suitably prepared) document source. More detailed information on BibTeX is then given in Chapter 13. In the current chapter we are only interested in how BibTeX can be used to produce a bibliography list.

Armed with this knowledge we plunge into a detailed discussion of how LaTeX supports the different citation schemes. At the time we wrote the first edition of this book, LaTeX basically supported the “number-only” system. A decade later, the situation has changed radically. Today, most major citation schemes are well supported by extension packages.

We end this chapter by discussing packages that can deal with multiple bibliographies in one document. This is not difficult if the reference lists are prepared manually, but it poses some challenges if you want to interact with BibTeX, as well.

The short-title system

In the short-title system, the reference to a source is given directly in the text, either inline or as a footnote, often in the form “Hart, Hart’s Rules, p. 52”. In the context of the publication, if abbreviations for the title are established, the form “Goossens et al., LGC” may appear as an alternative. Many variations exist. For instance, the first time a work is cited it might be presented with a lot of detail; later references might then use a shorter form—citing only the author’s name and a short title or the year. In case of repeated citations to the same work in direct succession, you might find Ibid. instead of a repeated reference. An implementation of the short-title system that allows all kinds of customizations is provided by the jurabib package (see Section 12.5.1).

Because in the short-title system a full reference is usually given the first time a work is cited, you can omit a list of references or a bibliography that contains all cited works in a single place.

The author-date system

In the author-date system (often referred to as the Harvard system after one of its better known typographical variants), references to sources are also given directly in the text. This time, however, they show the author’s name (or names) and the year of the publication. The full citation is given in a list of references or a bibliography. If the author published more than one work in a given year, that year is suffixed with lowercase letters (e.g., 2001a, 2001b).

There have been many attempts over the years to provide author-date citation support for LaTeX. With the natbib package (discussed in Section 12.3.2) there is now a very flexible and general solution available.

In all citation schemes that use author names, a work by three or more authors is usually referred to by using the name of the first author followed by et al. Especially with the author-date system, this may lead to ambiguous citations if different groups containing the same main author published in the same year. This problem can be seen in the following example.

Entries with multiple authors can be problematical, e.g., (Goossens et al. 1997) and (Goossens et al. 1997) or worse (Goossens et al. 1997; Goossens et al. 1997).

In the above example the bibliography is produced from the sample BibTeX database tex.bib shown in Figure 12.2 on page 690. This database is used in most examples in this chapter. Above we applied the BibTeX style chicago to it, a style that aims to implement a bibliography and reference layout as suggested by The Chicago Manual of Style [38].

One way to resolve such ambiguous citations is to use all author names in such a case, although that approach will lead to lengthy citations and is not feasible if the number of authors exceeds a certain limit. Another solution is to append a, b, and so on, to the year, even though the citations are actually for different author groups. This strategy is, for example, advocated in [29]. If the bibliography is compiled manually, as outlined in Section 12.1.2, this result can be easily achieved. When using BibTeX, you have to use a BibTeX style file that recognizes these cases and provides the right data automatically. For example, the style chicago cannot be used in this case, but all BibTeX styles produced with makebst (see Section 13.5.2) offer this feature:

The author-number system

In the author-number system, the references to the sources are given in the form of the author’s name (or names) followed by a number, usually in parentheses or brackets, indicating which publication of the author is cited. In the corresponding bibliography all publications are numbered on a per-author (or author group) basis. In the LaTeX world this system is fairly uncommon as it is difficult to produce manually. As far as we know, there is currently no BibTeX support available for it, though this situation might change in the future. A variation of the above is to number all publications sequentially. For this case suitable BibTeX styles exist.

The number-only system

Finally, in the number-only system, publications are sequentially numbered in the bibliography. Citations in the text refer to these numbers, which are usually surrounded by brackets or parentheses. Sometimes raised numbers are used instead. In a slight variation, known as “alpha” style, citations comprise the author’s name and the year of the publication. Thus, the bibliographic label and the citation may look like “[Knu86]”.

One argument against this system—put forward, for example, in The Chicago Manual of Style [38]—is that it raises the costs of publication since a late addition or deletion of a reference may require renumbering and consequently costly (and error-prone) changes to many pages throughout the manuscript. With automatic cross-referencing facilities as provided by LaTeX, this argument no longer holds true. In fact, the number-only system is the default system provided with LaTeX.

Numerical by first citation

A fairly popular form of the number-only system numbers the publications sequentially by their first citation in the text (and presents them in that order in the bibliography). This is fairly easy to provide with LaTeX. The next two sections and Section 12.2.3 explain how to avoid references in the table of contents that might mess up the expected order.

The widest-label argument is used to determine the right amount of indentation for individual items. If the works are numbered sequentially, for example, it should contain the number of items.

Individual publications are introduced with a ibitem command. Its mandatory argument is a unique cross-reference key that refers to this publication in the text. The optional argument defines the textual representation that is used in the citation and as the label in the list. If this argument is not specified, the publications are numbered with Arabic numerals by default. Within a publication the command ewblock may be used to separate major blocks of information. Depending on the layout produced by the class, it may result in a normal space, some extra space, or in starting a new line.

Producing a large bibliography manually in this way is clearly a tedious and difficult task and the result is normally not reusable, as nearly all journals and publishers have their own house styles with different formatting requirements. For this reason it is generally better to use BibTeX, a program that generates ready-touse LaTeX input from a database of bibliographical information. This is discussed in the next section.

Order by first citation done manually

Note that without the optional argument to ibitem the references are numbered in the order in which they appear in the bibliography. Thus, if you produce the bibliography manually, numbering and sorting them by order of first citation becomes your task. In contrast, when using BibTeX, this result can be achieved automatically.

Inside a document, publications are cited by referring to the cite-key arguments of the ibitem commands. For this purpose LaTeX offers the cite command, which takes such a key as its argument. It can, in fact, take a comma-separated list of such keys and offers an optional argument to specify additional information such as page or chapter numbers. The precise syntax is described in Section 12.2.1. For short-title or author-date citation schemes, additional citation commands are available once the supporting packages are loaded.

The BibTeX program gathers all citation keys used in a document, looks them up in a bibliographical database, and generates a complete thebibliography environment that can be loaded by LaTeX in a subsequent run. Depending on the BibTeX style used, it can either sort the entries according to some scheme (e.g., author names, year of publication) or produce a bibliography with entries in the order in which they appear in the .aux file. Note that using such a “nonsorting” style automatically generates a bibliography by order of first citation as required by the house styles of many publishers. An example of such a BibTeX style is unsrt.

The procedure for running LaTeX and BibTeX is shown schematically in Figure 12.1 on the next page. At least three LaTeX runs are necessary—first to produce data for BibTeX, then to load the result from the BibTeX run, and finally to resolve the cross-references to the bibliographical list added by the previous run.

To inform BibTeX which databases are to be searched to resolve citations, you should specify their names, separated by commas (and without the extension .bib), as an argument to the command ibliography. This command should be placed at the point where the bibliography should finally appear. In addition, you have to tell BibTeX how the bibliographic entries should be formatted. This is done by using the command ibliographystyle in the preamble with a suitable BibTeX style as its argument. It is, of course, important that the cite-keys used in the document uniquely identify an entry in the database file(s), so that the citation reference can be resolved when the document is processed.

To enable BibTeX to access the information without the need to parse the LaTeX source files, these commands write two lines to the .aux file. For a similar reason the cite command, as well as any variant of it, writes its key to this file. For example, in Example 12-1-2 the .aux file would contain (beside other entries):

Do not confuse these commands with those intended for use in the document. They exist solely to facilitate internal communication between LaTeX and BibTeX. If you mistakenly use ibdata instead of ibliography, then LaTeX will process your document without failure, but BibTeX will complain that it does not find any database information in the .aux file.

The precise format of a BibTeX entry will be described in detail in Chapter 13. To be able to understand the examples in the next sections more easily, you should nonetheless know that the basic structure of a BibTeX entry consists of three parts:

1. A publication entry type (e.g., “book”, “article”, “inproceedings”, “phdthesis”).

2. A user-chosen keyword identifying the publication. If you want to reference the entry in your document, then the argument cite-key of the cite command should be identical (also in case) to this keyword.

3. A series of fields consisting of a field identifier with its data between quotes or curly braces (e.g., “author”, “journal”, and “title”).

A sample database is shown in Figure 12.2 on the following page. This database is used in most examples throughout the chapter to show how applying different BibTeX style files to it results in different presentation forms.

Various schemes exist for conveniently associating bibliography keywords with their entries in a database. A popular one is the so-called Harvard system, where you take the author’s surname (converted to lowercase) and the year of publication, and combine them using a colon (e.g., smith:1987).

BibTeX entries are read by BibTeX in the bibliography database (the .bib file), and the formatting of the entries is controlled by an associated bibliography style (the .bst file), which contains a set of instructions written in a stack-based language. The latter is interpreted by the BibTeX program (see Section 13.6).

BibTeX knows which fields are required, optional, and ignored for any given entry type (see Table 13.1 on page 763). It will issue warnings, such as “author name required”, if something is missing. The style file can control the typesetting of both the citation string in the main text and the actual bibliography entry inside the thebibliography environment.

It is important to remember that BibTeX is not required for managing citations (except for the package jurabib and those packages intended for producing multiple bibliographies). You can produce a bibliography without BibTeX by providing the bibliographic entries yourself using the syntax described in Section 12.1.2. It is also a simple matter to manually edit the output from BibTeX to cope with special cases. Moreover, if your LaTeX document has to be self-contained, you can include the contents of the .bbl file in your document.

This database uses different conventions in individual entries (e.g., lower-, upper-, or mixed-case field names, different indentations) to show some features and problems in later examples. By applying one of the tools from Section 13.4 it could be normalized.

The cite command associates each keyword in the list in its mandatory argument with the argument of a ibitem command from the thebibliography environment to produce the citation reference. As with other LaTeX identifiers, these keys are case-sensitive.

The citation numbers generated are defined by the order in which the keys appear on the ibitem commands inside the thebibliography environment or, if an optional argument is used with ibitem, by the data provided in that argument.

The optional parameter text is an additional note, which will be printed together with the text generated by the cite command as shown in the following example. For comparison we have used an unbreakable space (~) in the first citation and a small space (,) in the second. Of course, such typographical details should be handled uniformly throughout a publication.

A note on the examples in this chapter

To save space, the examples in this chapter often omit the bibliography list. They are generated by placing ibliography{tex} at the end of the example document when automatically generating the example output for the book. Thus, you should read examples such as 12-2-1 as follows: the result is produced by generating the bibliography with BibTeX, applying the style plain (shown), and using the database tex.bib (not shown; see Figure 12.2). Thus, the actual document that produced the example contained ibliography{tex} near the end.

In conjunction with BibTeX, you can use the ocite variant of the cite command. Its sole purpose is to write the keys from the key-list argument into the .aux file, so that the associated bibliography information will appear in the bibliography even if the publication is otherwise not cited. For technical reasons it has to appear after egin{document}, even though it does not produce any output and would logically be best placed in the preamble. It can be used as often as necessary. As a special case ocite{*} includes all entries of the chosen BibTeX data in the list of references.

As stated above, the association between a cite command and one or more bibliography entries is made via the key-list argument. The citation text, which will actually appear in the typeset text, depends on the chosen bibliographic style.

Even worse, the user-level cite command sets the internal temporary switch @tempswa to indicate whether an optional argument was present. Thus, if we want to handle that optional argument, we need to evaluate the value of that switch. The @cite command receives two arguments: the list of obtained references and the note (if present). In the following example we typeset (#1 and, if @tempswa is true, follow it by a comma and ⊔#2. This is then followed by the closing parenthesis. The olinebreak[3] ensures that a break after the comma is taken only reluctantly.

The redefinition of @cite for purposes like the above can be avoided by loading the cite package; see Section 12.2.2.

For the thebibliography environment, which holds the list of the actual references, the situation is unfortunately not much better—the default implementation offers few customization possibilities. To modify the layout of the labels in front of each publication (e.g., to omit the brackets), you have to change the internal LaTeX command @biblabel.

Packages that implement a variation of the author-date system (e.g., the apalike, chicago, or natbib package), typically unconditionally redefine @biblabel to simply swallow its argument and typeset nothing. After all, such a bibliography is used by looking up the author name, so a label is unnecessary. The natbib package is somewhat more careful: if it detects that @biblabel was changed, then it honors the redefinition.

As mentioned earlier, different blocks of information, such as the authors or the title, are separated inside one ibitem in the bibliography by ewblock commands, which are also automatically inserted by most BibTeX styles. Normally, bibliographic entries are typeset together in one paragraph. If, however, you want your bibliography to be “open”, with each block starting on a new line with succeeding lines inside a block indented by a length ibindent (default 1.5em), then the class option openbib should be specified. This option is supported by all standard classes. The result is shown in the next example; we also redefine @biblabel to get raised labels.

This situation can be easily improved by simply loading the cite package (by Donald Arseneau), as in the following example:

By default, the cite package sorts citation numbers into ascending order, representing three or more consecutive numbers as a number range. Any non-numeric label is moved to the front (in the above example the “?” generated by the unresolved reference). If sorting is not desired you can globally prevent it by loading the package with the option nosort. Compression into ranges can be suppressed by using the option nocompress.

Customizing the citation layout

To customize the typeset reference the cite package offers a number of commands. For example, citeleft and citeright determine the material placed on the left and right sides of the citation string, respectively. These commands can be used to typeset parentheses instead of brackets as seen in the following example, which should be compared to Example 12-2-2 on page 692. We can also redefine citemid, the separation between citation and optional note, to produce a semicolon and a space.

Customizing breaks within citations

Another important aspect of citation management is controlling the behavior near the end of a line. Consider the string “see [2–3,7,13]”. Besides not allowing any kind of line break within this string, one could allow breaking after the “see”, after the commas, or after the en dash in a range.

By default, the cite package discourages line breaks before the citation with olinebreak[3], discourages line breaks after a comma separating the optional note with olinebreak[2], and very strongly discourages line breaks after en dashes in a range and after commas separating individual citation numbers. You can control the last three cases by redefining citemid, citedash, and citepunct. For example, to prevent breaks after the en dashes while allowing breaks after commas without much penalty, you could specify

There are several interesting points to note here. All three definitions are responsible not only for controlling any line breaks but also for adding the necessary punctuation: a dash for the range, a comma and a full blank before the optional note, or a comma and a tiny space between individual citations. For instance, if you want no space at all between citations, you can redefine citepunct to contain only a comma. The other important and probably surprising aspect is the mbox surrounding the en dash. This box is absolutely necessary if you want to control LaTeX’s ability to break at this point. TeX automatically adds a break point after an explicit hyphen or dash, so without hiding it in a box, the olinebreak command would never have any effect—the internally added break point would still allow a line break at this point. Finally, the hspace command allows for some stretching or shrinking; if you prefer a fixed space instead, remove the plus and minus components.

The high penalty that is added before a citation is hard-wired in the code. It is, however, inserted only if you have not explicitly specified a penalty in your document. For instance, “see~cite{..}” will be honored and no break will happen between “see” and the citation.

Customizing citation numbers

One more customization command, citeform, allows you to manipulate the individual reference numbers. By default, it does nothing, so the labels are typeset unchanged. In the following example we colored them. Other kinds of manipulation are possible, too (e.g., adding parentheses in Example 12-2-9).

The package offers an additional command, citen (its aliases are citenum and citeonline), that can be used to get a list of numbers without the surrounding citeleft and citeright (e.g., the default brackets). Other formatting is still done. In the next example we surround individual references to citations with parentheses, something that admittedly looks a little strange when used together with the default bracketing of the whole citation.

The package offers a number of options to handle standard configuration requests or to influence the package behavior in other ways. Some of them have already been discussed, but here is the full list:

adjust/noadjust Enables (default) or disables “smart” handling of space before a cite or citen command. By default, spaces before such commands are normalized to an interword space. If you write seecite{..}, a space is inserted automatically.

compress/nocompress Enables (default) or disables compression of consecutive numbers into ranges.

sort/nosort Enables (default) or prevents sorting of the numbers.

space A full interword space is used after commas, and breaking at this point is not actively discouraged. The default (option not specified) is to use a small space and to discourage, but allow, breaking.

nospace Eliminates the spaces after commas in the list of numbers, but retains the space after the comma separating the optional note. The result of this option is shown in Example 12-2-9 on the previous page. It is not the opposite of the space option!

verbose By default, cite warns only once per reference for undefined citations. When this option is specified, the warning is repeated each time an undefined reference is cited.

Citations with superscript numbers

The latest release of the cite package can also display citation references as superscript numbers if the package is loaded with the option superscript (or super). In the past this ability was provided by the separate package overcite (developed by the same author), which is still available for compatibility reasons.

If the cite command is used with an optional argument, then the whole list of citations will be typeset as though the cite package was loaded without the superscript option.

With the superscript or super option in effect, the customization commands citeleft, citeright, and citemid affect only citations with an optional argument, while citedash, citepunct, and citeform affect all citations. For details of their use, see the discussion on pages 694–695.

You will probably not need to change your source document, regardless of whether the superscript option is used. In particular, a space before the citation command will be ignored if the citations are raised. In principle, you can add this option without having to adjust your document sources, provided your writing style does not use the numerical citation as part of the sentence structure, as in the above example.

If superscript numbers are used for citation labels, special care is needed when punctuation characters surround the citation. By default, the cite package automatically moves a punctuation character following a citation in front of the superscript. Punctuation characters that will migrate in this way are stored in the command CiteMoveChars, with “.,;:” being the default (! and ? are not included, but can be added). A problem that can result from this process is doubling of periods. This case is detected by the package and one punctuation character is suppressed; see the second citation in the next example.

Unfortunately, with capitalized abbreviations or the use of @ after a period, the suppression of double periods fails. Possible workarounds are shown in the next example. Note, however, that the solution with U.S.A@. only works together with the cite package, but it gives the wrong spacing if no citation is present (you are effectively claiming that the sentence ends after the abbreviation)!

There is yet another pitfall that you may encounter: the final punctuation character does not migrate inside a preceding quotation—a style, for example, advocated by The Chicago Manual of Style [38]. In this case you may have to rewrite part of your source text accordingly.

The main options of the cite package were discussed on page 695. Three more options related to raising the reference numbers exist. With the option nomove specified, punctuation characters are not migrated before the superscript citation. With the option ref specified, citations with an optional argument have the word “Ref.” prepended. This is internally implemented by changing citeleft, so if you want a different string or want to change from brackets to, say, parentheses, you have to redefine the customization commands instead of using this option.

Finally, the biblabel option raises the labels in the bibliography. (By default, they retain their default layout regardless of whether you use the option superscript or its alias super.)

You can circumvent this problem by specifying an optional argument for caption, section, or similar commands without the citation, so that no citations will be written into such tables. If you have to use citations in these places, then a “manual” solution is to first delete any auxiliary files left over from previous LaTeX runs, then run LaTeX once, and then run BibTeX. In that case BibTeX will pick up only citations from the main document. Clearly, this approach is prone to error and you may find that your citation order got mangled after all when you finally see your article in print.

Donald Arseneau developed the small package notoccite to take care of this problem by redefining the internal command @starttoc in such a way that citations do not generate citation commands for BibTeX within the table of contents and similar lists. Simply loading that package will take care of the problem in all cases—provided you have not used some other package that redefines @starttoc (for example, notoccite cannot be combined with hyperref or the AMS document classes).

Consequently, anyone developing support for the author-date system has had to extend the LaTeX syntax for citing publications. The following example shows the two forms and their implementation (with two new commands) as provided by the natbib system.

Extending the LaTeX syntax for citing publications does not solve the problem completely. In order to produce the different forms of citation references needed in the author-date system, the information that is passed back from the bibliography through the optional argument of the ibitem command needs to be structured. Without a special structure it is impossible to pick up the data needed for the textual references (e.g., producing just the year in parentheses). That is, a bibliographical entry like

will allow the cite command to produce “(Donald E. Knuth 1986)” but not “Donald E. Knuth (1986)” or just “Knuth” or just “1986” as well. You also have to ensure that ibitem does not display the label, but that outcome can be fairly easily arranged.

The solution used by all implementations for author-date support is to introduce a special syntax within the optional argument of ibitem. In some implementations this structure is fairly simple. For instance, chicago requires only

This information can still be produced manually, if needed. Other packages go much further and encode a lot of information explicitly. For example, jurabib asks for the following kind of argument structure (same publication):

As we shall see (Section 12.5.1), this approach gives a lot of flexibility when referring to the publication, but it is clear that no one wants to produce a bibliography environment with such a structure manually. Hence, the only usable solution in this case is to use an external tool like BibTeX to generate the entries automatically.

For example, the chicago package, which aimed to implement the recommendations of The Chicago Manual of Style [38], offers the following list of commands (plus variants all ending in NP to omit the parentheses—for example, citeNP):

Several BibTeX styles (chicago, chicagoa, jas99, named, and newapa) are compatible with the chicago package. All of them are still in use, even though the package itself is rarely included in LaTeX distributions these days (natbib can be used instead to provide the user-level syntax).

In contrast, only two commands are provided by David Rhead’s authordate1–4 package, the original support package for the BibTeX styles authordate1 to authordate4. It implements recommendations by the Cambridge and Oxford University Presses and various British standards.

As a final example we look briefly at the harvard package by Peter Williams and Thorsten Schnier. In contrast to the two previously described packages, harvard has been further developed and updated for LaTeX2ε. It implements a number of interesting features. For example, a first citation gives a full author list, whereas a later citation uses an abbreviated list (unless explicitly requested otherwise). The user-level commands are shown in the next example.

The harvard package requires a specially prepared bibliography environment in which ibitem is replaced by harvarditem, a command with a special syntax used to carry the information needed for author-date citations. A few BibTeX styles (including agsm, dcu, kluwer, and nederlands) implement this special syntax.

Many of these packages support the author-date system quite well. Nevertheless, with different packages using their own syntax and supporting only half a dozen BibTeX styles each, the situation stayed unsatisfactory for a long time. Matters changed for the better when Patrick Daly published his natbib support package, described in the next section.

To solve the problem of incompatible syntaxes described in the previous section, Patrick Daly developed the natbib package (for “NATural sciences BIBliography”). This package can accept several ibitem variants (including harvarditem) as produced by the different BibTeX styles. Thus, for the first time, (nearly) all of the author-date BibTeX styles could be used with a single user-level syntax for the citation commands.

The natbib package is compatible with packages like babel, chapterbib, hyperref, index, and showkeys, and with various document classes including the standard LaTeX classes, amsbook and amsart, classes from the KOMA-Script bundle, and memoir. It cannot be used together with the cite package, but provides similar sorting and compressing functions via options.

The natbib package therefore acts as a single, flexible interface for most of the available bibliographic styles when the author-date system is required. It can also be used to produce numerical references, as we will see in Section 12.4.1.

Both commands take one mandatory argument (the key-list that refers to one or more publications) and one or two optional arguments to add text before and after the citation. LaTeX’s standard cite command can take only a single optional argument denoting a post-note. For this reason the commands implement the following syntax: with only one optional argument specified, this argument denotes the post-note (i.e., a note placed after the citation); with two optional arguments specified, the first denotes a pre-note and the second a post-note. To get only a pre-note you have to add an empty second argument, as seen in lines 4 and 8 in the next example. Also note that natbib redefines cite to act like citet.¹

¹ To be precise, cite is redefined to act like citet if natbib is used in author-date mode as discussed in this section. If used in author-number mode (see Section 12.4.1), it works like citep.

Both commands have starred versions, citet* and citep* (with otherwise identical syntax), that will print the full list of authors if it is known.¹ These versions will work only when this feature is supported by the used BibTeX style file. In other words, the information must be made available through the optional argument of ibitem; if it is missing, the abbreviated list is always printed.

¹ If you plan to also use the jurabib package (see Section 12.5.1), then avoid the starred forms as they are not supported by that package.

Two other variant forms exist: citealt works like citet but does not generate parentheses, and citealp is citep without parentheses. Evidently, some of the typeset results come out almost identically.

When using the author-date system it is sometimes desirable to just cite the author(s) or the year. For this purpose natbib provides the following additional commands (citeauthor* is the same as citeauthor when the full author information is unavailable):

Forcing names to upper case

Even more complex mixtures of text and citation information can be handled with the command citetext. It takes one mandatory argument and surrounds it with the parentheses used by other citation commands. By combining this command with citealp or other commands that do not produce parentheses, all sorts of combinations become possible.

Sometimes a sentence starts with a citation, but the (first) author of the cited publication has a name that starts with a lowercase letter. In that case the commands discussed so far cannot be used. The natbib package solves this problem by providing for all commands variants that capitalize the first letter. They are easy to remember: just capitalize the first letter of the corresponding original command. For example, instead of citet*, use Citet*. Here are some additional examples.

As a final goody, natbib lets you define alternative text for a citation that can be used instead of the usual author-date combination. For the definition use defcitealias (usually in the preamble), and for the retrieval use citetalias or citepalias.

With the commands introduced in this section, natbib offers the same features (with minor differences) as other support packages for the author-date system (e.g., the packages described in Section 12.3.1). In addition, it provides features not found elsewhere. On the other hand, in a few cases natbib does not offer directly equivalent commands. For example, harvard’s possessivecite command (shown in Example 12-3-4) has no direct correspondence in natbib, but it can be easily built manually. To emulate it, you can either directly use citeauthor and citeyearpar, as is done in the first line of the next example, or define your own command if this type of construction is used more often.

The last line in the previous example exhibits a potential problem when using several keys in one citation command: the references are typeset in the order of the key-list. If you specify the option sort, then the citations are sorted into the order in which they appear in the bibliography, usually alphabetical by author and then by year.

While all the citation commands support key-lists with more than one citation key, they are best confined to citep; already citet gives questionable results. The situation gets worse when you use optional arguments: with citet any pre-note is added before each year (which could be considered a defect in the package). More generally, it is not at all clear what these notes are supposed to refer to. Hence, if you want to add notes it is better to separate your citations.

Some BibTeX style files are quite cleverly programmed. For example, when the agsm BibTeX style, used in the previous example, detects that shortening a list of authors leads to ambiguous citations, it will refuse to produce an abbreviated list. Thus, after adding the test97 citation to the example, all citations suddenly come out in long form.¹ BibTeX styles produced with makebst avoid such ambiguous citations by adding a suffix to the year, but other BibTeX styles (e.g., chicago) happily produce them; see Example 12-3-18 below.

¹ Something that puzzled the author when he first encountered it while preparing the examples.

Some publications have so many authors that you may want to always cite them using their abbreviated name list, even the first time. You can achieve this effect by listing their keys, separated by commas, in the argument of the shortcites declaration. This example also shows that use of the chicago style can lead to ambiguous citations (lines 1 and 2 versus line 5).

By default, the citation layout is determined by the chosen BibTeX style (or natbib’s defaults if a given style is unknown to natbib). By including a citestyle declaration you can request to use the citation style associated with a BibTeX style that is different from the one used to format the bibliography. In the next example we use the agsm style for the citations while the overall style remains agu. If you compare this example to Example 12-3-19 you see that the textual formatting is unchanged (e.g., italic for author names), but the parentheses and the separation between authors and year have both changed.

It is also possible to influence the layout by supplying options: round (default for most styles), square, curly, or angle will change the type of parentheses used, while colon¹ (default for most styles) and comma will change the separation between multiple citations. In the next example, we overwrite the defaults set by the agu style, by loading natbib with two options.

¹ Despite its name this option will produce a “;” semicolon.

Yet another method to customize the layout is mainly intended for package and/or class file writers: the ibpunct declaration. It takes seven arguments (the first optional) that define various aspects of the citation format. It is typically used to define the default citation format for a particular BibTeX style. For example, the natbib package contains many definitions like this:

That definition will be selected when you choose chicago as your BibTeX style or when you specify it as the argument to citestyle. Similar declarations can be added for BibTeX styles that natbib does not directly support. This effect is most readily realized by grouping such declarations in the local configuration file natbib.cfg. For details on the meanings of the arguments, see the documentation accompanying the natbib package.

If there are conflicting specifications, then the following rules apply: the lowest priority is given to internal ibstyle@ 〈name〉 declarations, followed by the options specified in the usepackage declarations. Both are overwritten by an explicit ibpunct or citestyle declaration in the document preamble.

Forcing all author names on a single line

Normally, natbib does not prevent a line break within the author list of a citation. By specifying the option nonamebreak, you can ensure that all author names in one citation will be kept on a single line. In normal circumstances this is seldom a good idea as it is likely to cause overfull hboxes, but it helps with some hyperref problems.

For one particular situation natbib offers direct support: if you specify the option sectionbib, you instruct the package to use section*, even if the highest sectional unit is chapter. This option is useful if natbib and chapterbib are used together (see Section 12.6.1).

Between ibsection and the start of the list, natbib executes the hook ibpreamble, if defined. It allows you to place some text between the heading and the start of the actual reference list. It is also possible to influence the font used for the bibliography by defining the command ibfont. This hook can also be used to influence the list in other ways, such as setting it unjustified by adding aggedright. Note that both ibpreamble and ibfont are undefined by default (and thus need ewcommand), while ibsection needs redefining with enewcommand.

Finally, two length parameters are available for customization. The first line in each reference is set flush left, and all following lines are indented by the value stored in ibhang (default 1em). The vertical space between the references is stored in the rubber length ibsep (the default value is usually equal to itemsep as defined in other lists).

To show the various possibilities available we repeat Example 12-1-2 on page 685 but apply all kinds of customization features (not necessarily for the better!). Note the presence of par at the end of ibpreamble. Without it the settings in ibfont would affect the inserted text!

If the publication has no author but an editor, then most BibTeX styles will use the latter. However, if both are missing, the solutions implemented differ greatly. BibTeX files in “Harvard” style (e.g., agsm) use the first three letters from the key field if present; otherwise, they use the first three letters from the organization field (omitting “The⊔” if necessary); otherwise, they use the full title. If an entry has no year, then “n.d.” is used. This will result in usable entries except in the case where part of the key field is selected:

With the same entries, BibTeX styles produced with makebst (e.g., unsrtnat) use the following strategy: if a key field is present, the whole field is used as an “author”; otherwise, if an organization field is specified, its first three letters are used (omitting “The⊔” if necessary); otherwise, the first three letters of the citation label are used. A missing year is completely omitted. In case of textual citations, this means that only the author name is printed. In that situation, or when the key field is used, it is probably best to avoid citet and always use citep to make it clear to the reader that you are actually referring to a publication and not just mentioning some person in passing.

As a final example we show the results when using the chicago BibTeX style. Here the GNU manual comes out fine (the full organization name is used), but the entry with the date missing looks odd.

However, for this approach to work, it is important that the BibTeX style passes author-date information back to the document. Hence, .bst files, such as LaTeX’s plain, which have been developed for numerical citation systems only, are unable to transfer this information. In that case natbib will ignore the authoryear option and, if you use citet or one of its variants, you get warnings about missing author information and output similar to the following:

Here it is best to switch to a BibTeX style that supports the author-date system, such as plainnat instead of plain.

The index format is controlled by the internal command NAT@idxtxt. It has the following default definition:

Thus, it produces entries like “Knuth (1986)”. For citations without author or year information the results will most likely come out strangely. The citations in Example 12-3-24 will generate the following entries:

If you want to redefine the command, for example, to just generate the author’s name, you can do so in the file natbib.cfg or in the preamble of your document. In the latter case, do not forget makeatletter and makeatother!

It is also possible to produce a separate index of citations by using David Jones’s index package (see Section 11.4.3). It allows you to generate multiple index lists using the ewindex command. For this to work you must first declare the list and then associate automatic citation indexing with this list in the preamble:

Later on use printindex[cite] to indicate where the citation index should appear in the document.

doi For use with electronic journals and related material. The Digital Object Identifier (DOI) is a system for identifying and exchanging intellectual property in the digital environment, and is supposedly more robust than URLs (see http://www.doi.org for details). The field is optional.

eid As electronic journals usually have no page numbers, they use a sequence identifier (EID) to locate the article within the journal. The field is optional and will be used in place of the page number if present.

isbn The International Standard Book Number (ISBN), a 10-digit unique identification number (see www.isbn.org). The ISBN is defined in ISO Standard 2108 and has been in use for more than 30 years. The field is optional.

issn The International Standard Serial Number (ISSN), an 8-digit number that identifies periodical publications (see www.issn.org). The field is optional.

url The Uniform Resource Locator (URL) for identifying resources on the web. The field is optional. As URL addresses are typically quite long and are set in a typewriter font, line-breaking problems may occur. They are therefore automatically surrounded with a url command, which is given a simple default definition if undefined. Thus, by using the url package (see Section 3.1.8), you can drastically improve the line-breaking situation as then URLs can be broken at punctuation marks.

This command works as follows: instead of the usual ibliography command, which loads the .bbl file written by BibTeX and typesets the bibliography, you use obibliography with the same list of BibTeX database files. This command will read the .bbl and process the information, so that references to entries can be made elsewhere in the document. To typeset a citation with the full bibliographical information, use ibentry. The usual author-date citation can be produced with any of the natbib commands. Here is an example:

Potential pitfalls

There are a number of points to be noted here: the obibliography command must be placed inside the body of the document but before the first use of a ibentry command. In the preamble a obibliography will be silently ignored, and any ibentry command used before it will produce no output. Such a command is therefore best placed directly after egin{document}.

Another potential problem relates to the choice of BibTeX style. The bibentry package requires the entries in the .bbl file to be of a certain form: they must be separated by a blank line, and the ibitem command must be separated from the actual entry text by either a space or a newline character. This format is automatically enforced for BibTeX styles produced with makebst but other BibTeX styles may fail, including some that work with natbib.

The ibentry command automatically removes a final period in the entry so that the reference can be used in mid-sentence. However, if the entry contains other punctuation, such as a period as part of a note field, the resulting text might still read strangely. In that case the only remedy might be to use an adjusted BibTeX database entry.

One can simultaneously have a bibliography and use the ibentry command to produce full citations in the text. In that case, place the ibliography command to produce the bibliography list at the point where it should appear. Directly following egin{document}, add the command obibliography*. This variant takes no argument, because the BibTeX database files are already specified on the ibliography command. As a consequence, all publications cited with ibentry will also automatically appear in the bibliography, because a single .bbl file is used.

By default, natbib produces author-date citations. If you are primarily interested in citing references according to the number-only or author-number system, load natbib with the numbers option.

For comparison, we repeat Example 12-3-5 on page 701 with the numbers option loaded. This option automatically implies the options square and comma; thus, if you prefer round parentheses, use the option round and overwrite the default choice.

As you can see, the citet command now generates citations according to the author-number system, while citep produces number-only citations. In fact, if natbib is set up to produce numerical citations, LaTeX’s cite command behaves like citep. In author-date mode, natbib makes this command act as short form for the command citet.

All variant forms of citet and citep, as discussed in Section 12.3.2, are also available in numerical mode, though only a few make sense. For example, citep* gives the same output as citep, because there are no authors inside the parentheses.

The commands citealt and citealt* should probably not be used, as without the parentheses the citation number is likely to be misinterpreted. However, in certain situations citealp might be useful to obtain that number on its own and then perhaps use it together with citetext.

Some journals use numerical citations with the numbers raised as superscripts. If loaded with the option super, the natbib package supports this type of citation. In that case our standard example (compare with Example 12-4-1) will produce the following:

As you will observe, the use of the optional arguments produces somewhat questionable results; in the case of citep the pre-note will not appear at all. Thus, with this style of citation, it is usually best to stick to the basic forms of any such commands.

For superscript citations natbib removes possible spaces in front of the citation commands so as to attach the number to the preceding word. However, in contrast to the results produced with the cite package, punctuation characters will not migrate in front of the citation, nor is there any check for double periods. To illustrate this we repeat Example 12-2-11 from page 696.

The packages natbib and cite are unfortunately incompatible (both modify LaTeX’s internal citation mechanism), so in cases like Example 12-4-5 you have to change the input if natbib is to be used.

We have already encountered sort in connection with author-date citations. With numerical citations (i.e., the options numbers and super), the numbers are sorted. To show the effect we repeat Example 12-2-5 from page 693, except that we omit the undefined citation.

With the option sort&compress, the numbers are not only sorted but also compressed into ranges if possible. In author-date citation mode, this option has the same effect as sort.

If a BibTeX style supports author-date mode, then switching to numerical mode can be achieved by one of the following methods, which are listed here in increasing order of priority:

1. By selecting a ibliographystyle with a predefined numerical citation style (e.g., defined in a local configuration file, or in a class or package file).

2. By specifying the option numbers or super, as shown in most examples in this section.

3. By explicitly using ibpunct with the fourth mandatory argument set to n or s (for details, see the package documentation).

4. By explicitly using citestyle with the name of a predefined numerical bibliography style.

Similarly, you can manipulate the format of the number as typeset within the bibliography by redefining ibnumfmt using enewcommand.¹ The default definition for this command usually produces square brackets around the number.

¹ The package is unfortunately somewhat inconsistent in providing or not providing defaults for the customization hooks. This means that you have to use either ewcommand or enewcommand depending on the context.

While ibsection, ibpreamble, ibfont, and ibsep work as before, the parameter ibhang has no effect, since in a numbered bibliography the indentation is defined by the width of the largest number.

Besides short-title citations it offers support for author-date citations (by providing the natbib command interface), various options to handle specific requirements from the humanities, and special support for citing juridical works such as commentaries (hence the name jurabib).

The package uses an extended option concept where options are specified with a “key=value” syntax. The package supports more than 30 options, each of which may be set to a number of values, covering various aspects of presenting the citation layout in the text and the references in the bibliography. In this book we can show only a small selection of these possibilities. For further information refer to the package documentation, which is available in English and German.

Default used for all examples in this section!

It is inconvenient to handle so many options as part of the usepackage declaration, so jurabib offers the jurabibsetup command as an alternative. It can be used in the preamble or in the package configuration file jurabib.cfg (to set the defaults for all documents). Settings established when loading the package or via jurabibsetup in the preamble will overwrite such global defaults. For the examples in this section we will use the following defaults

and extend or overwrite them as necessary. Their meaning is explained below.

In contrast to natbib, the jurabib package requires the use of specially designed BibTeX style files. It expects a ibitem command with a specially structured optional argument to pass all kinds of information back to the user-level citation commands (see page 699). These BibTeX styles also implement a number of additional fields useful in conjunction with jurabib.

To show the particular features of jurabib, we use the small BibTeX database shown in Figure 12.3 on the facing page together with the database used previously (Figure 12.2 on page 690). If not explicitly documented otherwise, all examples in this section have the line

implicitly appended at the end when processed.

If two optional arguments are present, then the post-note argument moves to the second position, the same behavior found with the natbib syntax. But in the default set-up there is a big difference in that we do not have a pre-note argument but rather an annotator argument provided for a citation method used in legal works.¹ In that discipline, works often have an original author (under which the work is listed in the bibliography) as well as annotators who provide commentaries in the particular edition. These annotators are mentioned in the citation but not in the bibliography. Without further adjustments a citation will list only the author surnames (separated by slashes if there are several authors), followed by the annotator if present, followed by a possible post-note. If the BibTeX entry contains a shortauthor field, then it is used instead of the surnames. If you only want to specify an annotator, use an empty post-note. By default, a title or short title is shown only if the author is cited with different works in the same document.

¹ See page 721 if you want it to be a pre-note instead.

As you see, there is no way to determine from the typeset result that “Walker” is a co-author but “Heinrichs” is an annotator. To make this distinction immediately visible, jurabib offers a number of options implementing common citation styles. You can, for example, change the font used for the annotator, or change the separator between author and annotator. Both of these changes have been specified in the first part of the next example. You can also move the annotator before the author, a solution shown in two variants in the second part of the example.

Another way to clearly distinguish authors and annotators is to use the option authorformat with the keyword and (which replaces slashes with commas and “and”), the keyword dynamic (in which case different fonts are used depending on whether an annotator is present), or the keyword year (which moves the publication year directly after the author). The authorformat option can also be used to influence other aspects of the formatting of author names. Some examples are shown below. A complete list of allowed keywords is given in the package documentation. Note that if you use several keywords together (as done below), you need an additional set of braces to indicate to jurabib where the keyword list ends and the next option starts.

If the keyword dynamic is used, the annotator’s name is set in italics while the original author’s name is set in the body font.¹ For works without an annotator, author names are set in italics. One can think of this style as labeling those people who have actually worked on the particular edition.

¹ The fonts used can be customized by redefining the commands jbactualauthorfont and jbactualauthorfontifannotator.

The keywords and, dynamic, and year can be combined, while smallcaps and italic contradict each other with the last specification winning:

The information passed back by BibTeX is very detailed and structured into individual fields whose contents can be accessed using the citefield command.

The field argument is one of the following fields from the BibTeX database entry referenced by the key argument: author, shortauthor, title, shorttitle, url, or year. It can also be apy (address-publisher-year combination).

Whether more than a single key is useful is questionable for most fields. Indeed, even with cite multiple keys are seldom useful unless no optional arguments are present.

If you are familiar with the German language, you will notice that the hyphenation of “Schul-drecht” is incorrect: it should have been “Schuld-recht”. How to achieve this hyphenation automatically is explained on page 733.

If you compare the first two lines of the previous example with the BibTeX database files listed in Figure 12.3 on page 717, you see that the shorttitle field was used if available; otherwise, the title field was used. In fact, you will get a warning from jurabib for this adjustment: “shorttitle for aschur is missing – replacing with title”. A different approach is taken for entries of type article or periodical; there, a missing shorttitle is replaced by the journal name, volume number, and year of publication, which is why we got “TUGboat 10 [1989]”.

To force the production of a title in the citation, you can use citetitle instead of cite. To leave out the title, you can use cite*. You should, however, be aware that the latter command can easily lead to ambiguous citations, as shown in the next example.

Also note that this meaning of cite* is quite different from its use in natbib (where it denotes using a full list of authors). If you switch between both packages depending on the circumstances, it might be better to avoid it altogether.

It is also possible to refer to only the title, including a post-note if desired.

Getting short-title citations automatically

Short-title citations can be generated by default by specifying the option titleformat and the keyword all. Like authorformat, this option can take several keywords. We already know about colonsep, which we used as a default setting for all the examples. In the next example we overwrite it with commasep and print the titles in italic.

Instead of citing all works with titles you can select short-title citations based on a particular BibTeX type. For example,

would reference these three types with the title and all other publication types without it, unless the author is cited with several works. Since such a list can grow quite large, alternatively you can select automatic title citations for all works (with titleformat) and then specify those types that should have no titles when referenced. This is done in the next example for the type book. Nevertheless, the book by Knuth is cited with its title, since we also cite an article by him.

means that the author names will appear in italic in the index.

Instead of placing the author names in the main index, you can produce a separate author index by loading the index package (see Section 11.4.3) and then using a construction like

in the preamble, and later on printindex[authors] to indicate where the author index should appear in the document.

No support is available for more elaborate indexes as required for some types of law books (e.g., “Table of Cases” or “Table of Statutes”). If this is required, consider using the camel package instead of jurabib.

The see option replaces the default annotator optional argument with a pre-note argument in case two optional arguments are used. The cite command then has the same syntax and semantics as it does with the natbib package.

we will get the following bibliography listing. Note that the short title is formatted in exactly the same way as it will appear in the citation.

However, it is usually not necessary to display for all entries how they are cited. For articles, the short-title citation is always “author name, journal, volume, and year”. If a work is cited with its full title (i.e., if there is no shorttitle field) or if only a single publication is cited for a certain author, then the reader will generally be able to identify the corresponding entry without any further help. To allow for such a restricted type of “back-references”, jurabib offers the keywords compare, multiple, and normal.

If you use compare, then a back-reference is created only if the entry contains a shorttitle field and the title and shorttitle fields differ. With respect to Example 12-5-13 this means that only the first and last entries would show the back-references.

If you use multiple instead, then back-references are generated whenever an author is cited with several works except for citations of articles. In the above example, the first two entries would get back-references. If we also had a citation to Knuth-CT-a, then it would also show a back-reference, while Knuth’s article in TUGboat would be still without one.

Both keywords can be used together. In that case back-references are added to entries for authors with several publications as well as to entries whose short titles differ from their main titles.

Finally, there is the keyword normal (it is also used if you specify the option without a value). This keyword works slightly differently from the others in that it needs support to be present in the BibTeX database. If it is used, an entry gets a back-reference if and only if the BibTeX field howcited is present. The field can have two kinds of values. If it has a value of “1”, the back-reference lists exactly what is shown in the citation in text. With any other value, the actual contents of the howcited field are used for the back-reference, including any formatting directives contained therein.

The text surrounding the back-reference can be customized by redefining the commands howcitedprefix and howcitedsuffix. In addition, you can specify what should happen with entries that have been added via ocite by changing ibnotcited (empty by default). Because these commands may contain text that should differ depending on the main language of the document, they are redefined using a special mechanism (AddTo) that is explained on page 733.

This command works like cite but displays the full bibliographical data. The annotator, if present, will be placed in front of the citation just as if annotatorfirstsep=in had been specified.

Compare the next example with Example 12-3-27 from page 711. The keyword citationreversed arranges for the author name to appear with surname last (in the bibliography the surname comes first). Related keywords are allreversed (surname last in text and bibliography) and firstnotreversed (surname first for first author, last for all others in multiple-author works).

Getting full citations automatically

The cite command automatically generates full citations if the citefull option is specified together with one of the following keywords: all (all references are full citations), first (first citation is full, subsequent ones are abbreviated), chapter (same as first but restarts with each chapter), and section (like chapter but restarts at the section level). All settings imply annotatorfirstsep=in, as can be seen in the second citation in the example. If one of the above settings has been included in the configuration file and you want to turn it off for the current document, use the keyword false.

Further control is possible by specifying the BibTeX entry types for which a full citation should be generated on the first occurrence. In the example below (otherwise similar to Example 12-5-15), we request that only entries of type article should be subject to this process.

Sometimes it is not correct to make the first citation to a work be the full entry, such as in an abstract or preface. On the other hand, you may want to have a certain citation show the full entry again, even though it appeared earlier. For this purpose four commands are available that modify how individual citations are presented from the given point onward.¹

¹ The command names seem to indicate that they change the “next” citation, but in fact they change all further citations until they are overwritten.

If you use extciteshort, all citations specified in the key-list will be typeset as short-title citations from then on (e.g., lines A, B, D in the example). If you use extcitereset, the citations will (again) be typeset in the normal way; thus, the next citation will be a full citation if there has not been one yet (lines C and F) and otherwise citations will be set as short-title citations (line E). With extcitefull, you force full entries from then on (line G). With extcitenotitle, you get only the author name(s), even if it results in ambiguous citations.

If full citations are used within the main document it is not absolutely necessary to assemble them in a bibliography or reference list. You may, for example, have all citations inline and use a bibliography for suggested further reading or other secondary material.

This declaration lists those keys that should not appear in the bibliography even though they are cited in the text. The key-list is a list of comma-separated keys without any white space. You can repeat this command as often as necessary.

Think of it as the opposite of ocite. Both commands are used in the next example.

Suppressing the bibliography altogether

While citeswithoutentry prevents individual works from appearing in the bibliography it is not possible to use it to suppress all entries, as you would get an empty list consisting of just the heading. If you want to omit the bibliography altogether, use obibliography in place of the usual ibliography command. This command will read the .bbl file produced by BibTeX to enable citation references, but without producing a typeset result. You still need to specify jurabib as the BibTeX style and run BibTeX in the normal way.

The footnote citations produced by jurabib are ordinary footnotes, so you can influence their layout by loading the footmisc package, if desired.

Getting footnote citations automatically

If all your citations should be automatically typeset as footnotes, use the super option. In that case jurabib will automatically choose the foot.. variants, so cite will produce footcite, and so forth. This is shown in the next example. There we also use citefull=first so that the first footnote looks like the one in the previous example (to save space we show only the second page, where due to the ridiculously small height of the example page the last line of that footnote is carried over). The other two citations are then automatically shortened, with the third being shortened even further because of the ibidem option (explained on the following page).

We also use the option lookat, which is responsible for the back-reference to the earlier note containing the full citation. This option is allowed only if you simultaneously use the citefull option and have all your initial citations in footnotes, as it requires a “number” to refer to.

You have to be careful to use a footnote style that produces unique numbers. If footnotes are numbered by chapter or by page, for example, then such references are ambiguous. This problem can be solved by loading the varioref package, in which case these back-references will also show page numbers. If varioref is loaded for other reasons and you do not want page references in this place, use jbignorevarioref to suppress them. If footnotes are numbered by chapter, then an alternative solution is to use the labelformat declaration as provided by varioref to indicate to which chapter the footnote belongs:

The lookat option is particularly useful in combination with command obibliography, so that all your bibliographical information is placed in footnotes without a summary bibliography.

It is possible to customize the appearance of the back-references by using the commands lookatprefix and lookatsuffix. Both are language dependent, which is the reason for using the AddTo declaration (see page 733). The example sets up a style commonly seen in law citations [21].

By loading the endnotes package in a set-up similar to the one from the previous example, you can turn all your citations into endnotes. As you can see, the endnotes do not have a final period added by default. If you prefer a period, add the option dotafter with the keyword value endnote.

If ibidem is used without a value (which is the same as using it with the keyword strict), then the following happens: if a citation refers to the same publication as the immediately preceding citation on the current page, then it is replaced by “Ibid.”, if necessary keeping a post-note. You can see this situation in the next example: the first citation is a short-title citation; the second citation is identical so we get “Ibid.” with the post-note dropped; and the third and forth citations refer to different parts of the same publication so we get the post-note as well. The fifth citation refers to a different publication by the same authors, so another short-title citation is produced. The sixth citation refers to the same publication, but the short-title citation is repeated because it is on a new page. The seventh and eighth citations are again to the other publication, so we get first a short-title citation and then “Ibid.” with a post-note.

If you typeset your document with the class option twoside, then you can use the keyword strictdoublepage. It means that “Ibid.” will also be used across page boundaries as long as the preceding citation is still visible (i.e., on the same spread). Repeating Example 12-5-24 with this setting will change the sixth citation to “Ibid., §3”.

The ibidem option usually generates a lot of very short footnotes, so it might be economical to use it together with the para option of footmisc. We also add the perpage option so that the footnote numbers remain small. Note, however, that this makes it impossible to use the lookat option because the footnote numbers are no longer unique.

It is even possible to ignore all page boundaries by using the nostrict keyword. The reader might find it difficult to decipher the references, however, because “Ibid.” and the citation to which it refers may be moved arbitrarily far apart. If necessary, you can disable the ibidem mechanism for the next citation by preceding it with oibidem.

The use of “Ibid.” without any further qualification allows you to reference just the immediately preceding citation. Thus, if citations are frequently mixed, the mechanism will insert short-title references most of the time. This situation will change if you use the ibidem option with the keyword name (which automatically implies citefull=first). In that case “Ibid.” will be used with the full name of the author, thus allowing a reference to an earlier—not directly preceding—citation. If only the surnames of the authors are required, add the authorformat option with the keyword reducedifibidem. Its effect is seen in the next example, where citations to bschur and zpo alternate. A variant is to always use name and short title except for the first citation of a publication; this format can be requested with the keyword name&title.

If the same author is cited with more than one publication, then using the ibidem option with the name keyword is likely to produce ambiguous references. For those citations the jurabib package automatically switches to the name&title&auto method described below.

If name&title&auto was selected (either implicitly or explicitly), then the following happens: the first citation of a publication automatically displays the full entry (citation 5 in the next example). In case of repeated citations to unambiguous works only the name of the author(s) are shown (citation 8). For ambiguous citations this will be done only for immediately following citations (citation 4). However, if there are intervening citations, then the name(s) and short titles are shown (citations 3, 6, and 7).

Another convention in certain disciplines is to replace the author’s name with the Latin word “Idem” (meaning “the same”) if the author of successive citations is identical. This is catered for by the option idem, which accepts the keywords strict, strictdoublepage, and nostrict with the same semantics as used with the ibidem option. Both options can be combined as shown in the next example. Due to the keywords used we get different citations: some use “Idem, ibid.”; after the page break “Idem” is suppressed, because of the option strict; and in the last three citations it is used again (even with the full citation) because they all refer to different publications of Donald Knuth.

You have to ask yourself whether this type of citation is actually helpful to your readers. Butcher [29], for example, argues against it. Of course, you may not have a choice in the matter—it might be required. You should, however, note that two citations in the previous example are actually wrong: van Leunen is a female author, so the correct Latin form would be “Eadem” and not “Idem” (though some style manuals do not make that distinction). If necessary, jurabib offers possibilities for adjusting your citations even on that level of detail; see page 734.

There is another convention related to recurring citations, though it is becoming less common: to signal that a citation refers to an earlier reference, it is flagged with op. cit. (opere citato, “in the work cited”). This practice is supported with the option opcit. The citation should be “close by” so that the reader has a chance to find it. For this reason jurabib offers the keywords chapter and section in analogy to the citefull option.

In law citations [21], it is common to use the word “supra” to indicate a reference to a previous citation. This can be accomplished by changing the opcit command, which holds the generated string, as follows:

Alternatively, you can use the method shown in Example 12-5-22 on page 727.

If BibTeX decides to produce separate entries for the cross-referenced citations, a question arises about what should happen if they are referenced in a fullcite or footfullcite command in the text. To handle this situation jurabib offers three keywords applicable to the crossref option: with the keyword normal (the default), cross-references are typeset as an author/editor, title combination (or shortauthor, shorttitle if available); with the keyword short, only the author or editor is used as long as there are no ambiguities; and with the keyword long, cross-references are listed in full. The default behavior is shown below (where the editors and the short title were selected by jurabib).

You can combine any of the three keywords with the keyword dynamic, in which case a cross-reference is given in a longer form when cited the first time and in the shorter form on all later occasions. Here we combine it with the keyword long so that we get a full citation to Vanoirbeek/Coray in the first citation and a short title citation in the second.

A combination of author-date and short-title citations is achieved by setting authorformat=year, as already introduced in Example 12-5-5. The formatting of the year can be influenced with jbcitationyearformat, and the position of the date can be moved after the title (if present) by specifying jbyearaftertitle.

The declaration AddTo takes two arguments: a command name that holds all language-related definitions for one language and the code that should be added to this storage place.¹ The first argument is either ibsall, in which case code is used for all languages, or ibs 〈language〉 (e.g., ibsgerman), in which case code is applied for that particular language.² In Example 12-5-14 on page 723 and Example 12-5-22 on page 727 we used AddTo to change the presentation of back-references for all languages, by adding the redefinitions to ibsall. Below we shorten the “Ibid.” string when typesetting in the English language. The default for other languages is left unchanged in this case.

¹ The babel package uses a similar mechanism with the addto declaration.

² Unfortunately, jurabib does not use exactly the same concept as babel. If you specify ngerman with babel to get German with new hyphenation patterns, then this is mapped to german, so you have to update ibsgerman. If you use any of the dialects (e.g., austrian), then jurabib will not recognize those and will use english after issuing a warning. In that case use ibsall for changing definitions.

While certain strings—calling an editor (editorname) “(Hrsg.)”, for example—should clearly be consistent throughout the whole bibliography, certain other aspects—most importantly, hyphenation—depend on the language used in the actual entry. For instance, a book with a German title should be hyphenated with German hyphenation patterns, regardless of the main language of the document. This is supported by jurabib through an extra field (language) in the BibTeX database file. If that field is specified in a given entry, then jurabib assumes that the title should be set in that particular language. Thus, if hyphenation patterns for that language are available (i.e., loaded in the format), they will be applied. For instance, if we repeat the last part of Example 12-5-6 from page 719 with babel loaded, we get the correct hyphenation:

Possible values and the commands that contain the “Idem” strings, if specified, are given in Table 12.1. The commands with an uppercase letter in their name are used at the beginning of a sentence, the others in mid-sentence. Those starting with ibidem.. are used in the bibliography if the option bibformat with the keyword ibidem is specified. Since the feature is computing intensive, it is not activated by default but has to be requested explicitly. Thus, to change to “Eadem” in case of female authors, we have to specify values for idemSfname and idemsfname and use the option lookforgender.

If the whole citation should be surrounded by parentheses, simply specify the option round or square.

To place information about the edition as a superscript after the short title, specify the option superscriptedition. With a value of all this will be applied to all short-title citations, with the keyword commented applying only to publications of type commented, and with the keyword multiple applying only to publications that are cited with several different editions. The last two options are primarily intended for juridical works.

Alternatively, you can explicitly specify in the BibTeX database for each entry whether the edition should be shown as a superscript by setting the special field ssedition to the value 1 and by using the option superscriptedition with the keyword switch.

By specifying authorformat=and you will get author names separated by commas and “and” (actually by andname, a command that has different values in different languages). But you cannot have the second and third author names separated by “, and” in this way. For adjustments on such a fine level, you can redefine jbbtasep (between two authors separation), jbbfsasep (between first and second authors separation), and jbbstasep (between second and third authors separation).¹

¹ No other possibilities are needed, since jurabib always uses “et al.” whenever there are four or more authors.

You may also want to manually specify the fonts used for the author names and the short title, instead of relying on the possibilities offered by the supplied options. For this you have jbauthorfont, jbannotatorfont, jbactualauthorfont, jbauthorfontifannotator, and jbtitlefont at your disposal, all of which are commands with one argument.

This means that formatting decisions, such as using emphasis for the title of the book and the series, and the presentation of the “volume” field, have all been made by the BibTeX style file.

In contrast, the BibTeX styles that come with the jurabib package use a drastically different approach: their output is highly structured, consisting of a large number of LaTeX commands, so that the final formatting (as well as the order of elements to some extent) can still be tweaked on the LaTeX level. In fact, they have to be adjusted on that level if you are not satisfied with the formatting produced from their default definitions. For example, the same citation as above processed with the jurabib BibTeX style results in the following entry:

Most of the above commands are further structured. The ibnf command takes five arguments (the different parts of the author’s name) and, depending on which are nonempty, passes them on to commands like jbnfIndNoVonNoJr (name without “von” and “Junior” parts) for further processing. Consequently, it is possible to interact with this process at many levels so that all kinds of requirements can be catered for, although this somewhat complicates the customization of the layout. For this reason we restrict ourselves to showing just the most important customization possibilities. For further control strategies, consult the package documentation.

In the default set-up, the formatting of the bibliography is fairly independent of that used for the citations. If you specify authorformat=italic, author names are typeset in italics in the text but there is no change in the bibliography. The easiest way to change that is to use the option biblikecite; then formatting decisions for the citations will also be used in the bibliography as far as possible. If that is not desired or not sufficient, explicit formatting directives are available; they are discussed below.

The fonts used in a bibliographical entry are controlled by the following set of commands: iblnfont and ibfnfont for formatting the last and first names of the author, and ibelnfont and ibefnfont for the last and first names of the editor, if present. The command ibtfont is used for titles of books, ibbtfont for titles of essays (i.e., entries involving a BibTeX booktitle field), and ibjtfont for titles, or rather names, of journals. The font for article titles within such a journal is customized with ibapifont. The commands all receive the text they act upon as an argument, so any redefinition must also use an argument or ext.. font commands as shown in the next example (picking the argument up implicitly).

The punctuation separating different parts in the entry can be customized by another set of commands: ibansep sets the punctuation and space after the author name, ibeansep does the same after the editor name, ibatsep produces punctuation after the title (the space is already supplied!), and ibbdsep is the punctuation before the date. With ibjtsep the journal title separation is set. There are similar commands for adjusting other parts.¹ In the next example we use these commands to remove the default colon after the author’s name and then typeset a semicolon after the title, no comma before the year, and the word “in” before the journal name. We also use the dotafter option with the keyword bibentry to add a final period after each entry.

¹ This area of jurabib is somewhat inconsistent in its naming conventions and command behavior. Perhaps this will change one day.

We already saw that the separation between different author names in a citation can be adjusted by means of the authorformat option and various keywords. However, except for the keyword allreversed, this has no effect on the entries in the bibliography. To modify the formatting there, you have to redefine the commands ibbtasep, ibbfsasep, and ibbstasep. The naming convention is the same as for the corresponding citation commands. A similar set of commands, ibbtesep, ibbfsesep, and ibbstesep, is available to specify the separation between editor names in an entry.

Adjusting the general layout of the bibliography

The main option for influencing the general layout of the bibliography list is bibformat, which can take a number of keywords as its value. If you specify the keyword nohang, then the default indentation (of 2.5em) for the second and subsequent lines of a bibliographical entry is suppressed. Alternatively, you can explicitly set the indentation by changing the dimension parameter jbbibhang, as in the next example. There we also use the keywords compress (using less space around entries) and raggedright (typesetting entries unjustified). For improved quality, especially when typesetting to a small measure, you may want to load the package ragged2e. Note the use of the newcommands option to overload the standard aggedright (as used by jurabib) with RaggedRight.

If you use the keyword tabular, then the bibliography is set in a two-column table with the left column containing the author(s) and the right column the remainder of the entry. By default, the first column is one third of extwidth and both columns are set ragged. The defaults can be changed by redefining a number of commands, as shown in the next example. The width of the right column is specified by

Normally it is enough to change ibleftcolumn and/or ibcolumnsep. The calc package is automatically loaded by jurabib, so we can make use of it when specifying dimensions.

If you use the keyword numbered, the bibliography will be numbered even though the actual citations in the text use the author-date or short-title scheme. Currently, it is impossible to refer to those numbers.

Some publishers’ house styles omit the author’s name (or replace it by a dash or other character) if that author is cited with several works. This is supported through the keyword ibidem, which by default generates “Idem” or, more precisely, the result from executing ibidemSmname. To get a (predefined) rule instead, use jbuseidemhrule. If you want something else, redefine ibauthormultiple. Both possibilities are shown in the next example. The jurabib package automatically detects if an entry appears on the top of a page and will use the author name in that case. Because of this mechanism it may take several (extra) LaTeX runs before the document compiles without “Rerun to get...”

A variant bibliography layout collecting works under the author names is available through the keyword ibidemalt. This keyword automatically implies the keyword compress.

Annotated bibliographies

If you want to produce an annotated bibliography, use the option annote. If the current BibTeX entry has an annote field, it will be typeset after the entry using jbannoteformat to format it (the default is to typeset it in small). If there is no annote field, then jurabib searches for a file with the extension .tex and the key of the entry as its base name. If this file exists, its contents will be used as the annotation text.

Since it is a nuisance to have many files (one for each annotation) cluttering your current directory, jurabib offers a search path declaration in analogy to the graphicspath command provided by the graphics package. Thus, after

annotation files are searched for in the subdirectories books and articles of the current directory.

will load the option file law.cfg, which should contain a jurabibsetup declaration and possibly some additional customization commands. For example, such a file might contain

and perhaps some other initializations to implement citations for juridical publications. As mentioned earlier, such defaults stored in a file can be overwritten by using additional options during loading or with a jurabibsetup declaration in the preamble.

All four styles provide a number of additional BibTeX entries as well as a number of additional fields for existing entries. Having additional fields in a BibTeX database is usually not a problem, since BibTeX ignores any field it doesn’t know about. Thus, such a database can be used with other BibTeX styles that do not provide these fields. Additional entries are slightly different, since using them means you have to use jurabib to be able to refer to them.

Additional BibTeX types

The additional entries are www for citing a URL, periodical for periodicals that are not cited by year but by volume number, and commented for commentaries in juridical works.

The standard BibTeX fields are described in Table 13.2 on page 765. The following additional fields are available when using one of the jurabib BibTeX styles:

annote An annotation that is typeset if jurabib is used with the option annote; see page 740 for details.

booktitleaddon Extra information to be typeset after a booktitle text of a collection.

dissyear Year of a dissertation, habilitation, or other source if that work is also being published as a book (perhaps with a different year).

editortype Position of the person mentioned in the editor field (if not really an “editor”).

flanguage Foreign language, in case of a translated work.

founder In juridical works, the original founder of a publication (in contrast to the editor). The name is shown followed by the replacement text of foundername, which defaults to “⊔(Begr.)”.

gender Gender of the author or authors. The jurabib package uses this information to select the right kind of words for “Idem” in the current language; see page 734.

howcited Text to use for back-reference information, or 1 to indicate that a normal back-reference should be generated. This field is evaluated by the option howcited if used together with the keyword normal; see page 721.

oaddress/opublisher/oyear Information about the first edition of a work.

shortauthor Text to use as the author information in a short-title citation. By default, jurabib automatically selects the last name (or names) from the author or editor field.

shorttitle Text to use as the title information in a short-title citation. If it is not specified the whole title is used.

sortkey String to be used for sorting in unusual situations. To sort “von Bismarck, Otto” under B, you can use sortkey="Bismarck, Otto von".

ssedition Flag to indicate that this entry should be typeset with the edition shown as a superscript. It requires the use of the superscriptedition option together with the keyword switch; see page 735.

titleaddon Extra information to be placed after a title but not used, for example, when generating a short title.

totalpages Total number of pages in a publication. If present, it will be shown followed by the replacement text of the command ibtotalpagesname, which is language dependent.

translator Translator of the publication.

updated Date of the last update in a loose-leaf edition or a similar work. The field is only available for the BibTeX type commented. By default, “last update date” is generated. This can be customized through the commands updatename and updatesep.

urldate Date when a URL was known to be current. By default, jurabib produces the string “visited on date” when this field is used. It can be changed by redefining the command urldatecomment.

url A URL related to the current publication. In case of the entry type www, it is required; otherwise, it is optional.

volumetitle A volume title that follows the volume number in the presentation. This field is available for the types book, commented, incollection, and inbook.

In contrast to the packages described so far, camel uses its own set of commands to specify citations (source instead of cite), bibliographical databases (citationdata instead of ibliography), citation conventions (citationstyle instead of ibliographystyle), and printed bibliographies (printbibliography as the second part of the functionality of ibliography).

The next example shows these commands in action. The source command takes an optional first argument in which one can specify what kind of citation should be given (e.g., “f” for full reference, “t” for title omitted, “a” for author name omitted). A second optional argument after the key can be used to specify page numbers in the reference.

An interesting feature is that the package recognizes so-called interword connectors between citations (e.g., “see-also” and “cited-in” in our example). As a result those citations are considered to belong together and are automatically placed into the same footnote.

Another feature that can be of interest is the ability to produce subject bibliographies using the citationsubject declaration.

The citation data are written to external files (extension specified with o= on the citationsubject declaration). Such files have to be processed by MakeIndex:

The results are then read back in (i= argument) on the next LaTeX run.

A complementary request is to have several bibliographies in parallel, such as one for primary sources and one for secondary literature. In that case one has to be able to reference works in different bibliographies from any point in the document.

Both requests can be automatically resolved if none of the bibliographies contain the same publication¹ and you are prepared to produce the bibliographies manually, by means of several thebibliography environments without using BibTeX. In that case the ibitem commands within the environment provide the right cross-referencing information for the cite commands (or their variants) to pick up from anywhere in the document. Having the same publication in several bibliographies (or more exactly the same reference key) is not possible, since that would lead to a “multiply defined labels” warning (see page 928) and to incorrect references. Of course, this could be manually corrected by choosing a different key for such problematical citations.

¹ This could happen, for example, if you compile the proceedings of a conference and each article therein has its own bibliography.

Being deprived of using BibTeX has a number of consequences. First, it will be more difficult to impose a uniform format on the bibliographical entries (something that BibTeX automatically handles for you). Second, using an author-date or short-title citation scheme will be difficult (since natbib requires a special structure within the optional argument of ibitem) to downright impossible (since the structure required by jurabib is not suitable for manual production); see Section 12.3 for a discussion of the required ibitem structures in both cases.

To be able to use BibTeX for this task people had to find a way to generate several .bbl files from one source document. As discussed in Section 12.1.3, the interaction with BibTeX normally works as follows: each citation command (e.g., cite) writes its key-list as a citation command into the .aux file. Similarly, ibliography and ibliographystyle commands simply copy their arguments to the .aux file. BibTeX then reads the master .aux file (and, if necessary, those from included files) searching for occurrences of the above commands. From the provided information it produces a single .bbl file. To make BibTeX work for the above scenarios, four problems have to be solved:

1. Generate one .aux file for every bibliography in the document that can be used as input for BibTeX.

2. Ensure that each citation command writes its information to the correct .aux file, so that BibTeX, when it processes a given .aux file, will add the corresponding bibliographical data in the .bbl file but not in the others.

3. Ensure that the resulting .bbl files are read back into LaTeX at the right place.

4. Handle the problem of escaping citations due to their placement in sectioning or caption commands. A citation in such a place would later appear in the table of contents or list of figures, and there (in a different context) LaTeX would have problems in resolving it.

The packages chapterbib, bibunits, bibtopic, and multibib, which are described in this section, solve the above problems in different ways. They all have their own advantages and disadvantages. A short comparison of these packages appears in Table 12.2, where blue entries indicate features (or missing features) that may force a selection when one is looking for a solution for bibliographies per unit or with bibliographies per topic, or a combination of both.

It solves the problem of producing several .aux files for BibTeX, by relying on the include mechanism of LaTeX; you can have one bibliography per included file. This package can be used, for example, to produce a document with bibliographies per chapter (hence the name), where each chapter is stored in a separate file that is included with the include command. This approach has the following restrictions:

• Each include file needs to have its own ibliography command. The database files that are listed in the argument can, of course, be different in each file. What is not so obvious is that each file must also contain a ibliographystyle command, though for reasons of uniformity preferably with the same style argument (Example 12-6-1 on the next page shows that different styles can be applied).

• An include file not containing a ibliography command cannot contain citation commands, as they would not get resolved.

• Citation commands outside of include files (with the exception of those appearing in the table of contents; see below) will not be resolved, unless you include a thebibliography environment on that level. Without special precautions, this environment has to be entered manually. If you use BibTeX on the document’s .aux file you will encounter errors, because BibTeX sees multiple ibdata and ibstyle commands (when processing the included .aux files). In addition, you will get all citations from all include files added, and that is perhaps not desirable. If you do want a cohesive bibliography for the whole document, there is a rootbib option to help with this task. However, it requires adding and removing the option at different stages in the process; see the package documentation for details.

• Units containing a local bibliography will always start a new page (because of the include command). For cases where this is not appropriate, chapterbib offers some support through a cbinput command and cbunit environment; see the package documentation for details. Unless you need the gather option, it might be better to use the bibunits package in such situations.

By default, the thebibliography environment generates a numberless heading corresponding to the highest sectioning level available in the document class (e.g., chapter* with the book class). However, if bibliographies are to be generated for individual parts of the document this may not be the right level. In that case you can use the option sectionbib¹ to enforce section* headings for the bibliographies.

¹ If both chapterbib and natbib are used, use the sectionbib option of natbib instead!

In the following example, we present the include files article-1.tex and article-2.tex in filecontents environments, which allows us to process this example automatically for the book. In real life these would be different files on your computer file system. We also use stepcounter to change the chapter counter rather than using chapter to avoid getting huge chapter headings in the example. Note that both included files refer to a publication with the key Knuth-CT-a. These are actually treated as different keys in the sense that one refers to the publication from article-1.bbl and the other refers to that from article-2.bbl.

If you wish to group all the bibliographies together (for example, at the end of the document), use the option gather and place a ibliography command at the point where the combined bibliography should appear. The argument to that command can be left empty as it is not used to communicate with BibTeX.

Instead of gather, you may want to use the option duplicate. It will produce “chapter bibliographies”, plus the combined listing. Both options work only in document classes that have a chapter command. The headings generated by either option can be customized by redefining the command StartFinalBibs, which is executed at the point where the top-level ibliography command is encountered. In the following example it generates an unnumbered chapter heading, sets up the running head via chaptermark, and then redefines ibname, which provides the text used in the heading for each sub-bibliography. As you can see hechapter is used to number the sub-bibliographies, so this mechanism works only if all chapters have bibliographies; otherwise, the numbering will be wrong.

If you do not place the combined bibliography at the end of the document, make sure that ibname is properly reset afterwards. Otherwise, any subsequent bibliography in an include file will inherit the modified definition.

If the highest heading unit in your document is section, the redefinition of StartFinalBibs can be done in a similar way. You then have to use efname instead of ibname, since that is the command used in classes derived from the article document class.

If citations are placed into sectioning or caption commands they will appear eventually in some table of contents list (i.e., at the top level). Nevertheless, chapterbib will properly resolve them, by inserting extra code into .toc, .lof, and .lot files so that a cite command is able to determine to which local bibliography it belongs. If you have additional table of contents lists set up, as explained in Section 2.3.4, you have to be careful to avoid citations that may end up in these new contents lists, as chapterbib is unaware of them.

Command already defined error

Some BibTeX styles unfortunately use ewcommand declarations instead of providecommand in the generated .bbl files, which makes such files unsuitable for repeated loading. If you get “Command 〈name〉 already defined” errors for this reason, surround the ibliography commands and their arguments in braces. For example, write

The chapterbib package is compatible with most other packages, including the citation packages discussed earlier in this chapter. If you plan to use it together with babel, load the chapterbib package first.

One way to denote the units that should have a separate bibliography is by enclosing them in a bibunit environment.

Setting up defaults

The optional parameter style specifies a style for the bibliography different from a default that may have been set up (see below). Instead of ibliography you use a putbib command to place the bibliography. It can appear anywhere within the unit as proven by the example. The optional argument file-list specifies a comma-separated list of BibTeX database files; again a default can be set up. A default BibTeX style can be set with defaultbibliographystyle; without it, plain is used as the default. Similarly, defaultbibliography can be used to define a default list of BibTeX databases. In its absence jobname.bib is tried. To be effective the default declarations have to appear after egin{document}.

For each unit bibunits writes the citation commands (used to communicate with BibTeX) into the file bu 〈num〉.aux, where 〈num〉 is an integer starting with 1. Thus, to generate the necessary bibliographies, you have to run BibTeX on the files bu1, bu2, and so forth. As a consequence, with the default settings you cannot process more than one document that uses bibunits in the same directory, as the auxiliary files would be overwritten.¹

¹ If necessary, you can direct the package to use different names; see the package documentation.

After generating the bibliographies you have to rerun LaTeX at least twice to resolve the new cross-references. Be aware that older versions of the package do not warn you about the need for a further rerun.

A global bibliography, in addition to the bibliographies for the individual units, can be generated by using ibliography and ibliographystyle as usual. Outside of a bibunit environment, the standard commands should be used to generate a citation for the global bibliography. Inside bibunit, use cite* and ocite* instead of cite and ocite to generate a citation for both the local and the global bibliography. There are, however, a number of restrictions. If the natbib package is also loaded, then cite* has the meaning defined by natbib and cannot be used for generating a global citation (use ocite outside the unit in that case). In addition, refrain from using numerical citation labels, since they are likely to produce ambiguous labels in the global bibliography, as shown in the next example. A better choice would be a BibTeX style such as alpha.

Rather than using cite* everywhere in your document, you can specify the package option globalcitecopy. All local citations are then automatically copied to the global bibliography as well.

Instead of specifying the bibliography units with bibunit environments explicitly, you can specify the sectioning unit for which bibliography units should be generated automatically.

This command specifies for which document unit references must be generated, such as unit=chapter (for each chapter) or unit=section (for each section). If the optional argument is not given, the command ibliographyunit deactivates further bibliography units. When ibliographyunit is active, the ibliographystyle and ibliography commands specify the BibTeX files and the style to be used by default for a global bibliography, as well as in the local units. If you wish to specify information for local bibliographies only, use ibliography* and ibliographystyle* instead. These declarations cannot be used in the preamble but must be placed after egin{document}.

Getting unresolved references

There is, however, a catch with the approach: the normal definition of the thebibliography environment, which surrounds the reference lists, generates a heading of the highest sectioning level. Hence, if you use chapter units in a report, the heading generated by that environment will prematurely end the unit and consequently you will end up with undefined references, as shown in the example (using section units in an article class).

To resolve this problem, you can provide your own definition for the thebibliography environment, so that it uses a different sectioning level than the one specified on the ibliographyunit declaration. Alternatively, you can use the option sectionbib (use section* as a heading in thebibliography) or subsectionbib (use subsection*) to change the thebibliography environment for you.

Note that the unit specified on the ibliographyunit command has to be different from the one referred to in the option. In the above example the unit was section, so we used the subsectionbib option.

To resolve the problem of escaping citations (see page 746), the package offers the option labelstoglobalaux. However, this has the side effects that such citations will appear in the global bibliography and that numerical reference schemes are likely to produce incorrect labels; see the package documentation for details.

Within the document all citations are produced with cite, ocite, or variants thereof (if natbib or similar packages are also loaded). Thus, separation into topics is handled at a later stage. To produce separate bibliographies by topic you have to group the bibliographical entries that belong to one topic in a separate BibTeX database file (e.g., one for primary sources and one for secondary literature). The bibliographies are then generated by using several btSect environments. Ways to generate separate database files are described in Chapter 13. You can, for example, use the program bibtool to extract reference entries according to some criteria from larger BibTeX database collections.

The btSect environment generates a bibliography for all citations from the whole document that have entries in the BibTeX database files listed in the comma-separated file-list argument. If the optional style argument is present, it specifies the BibTeX style to use for the current bibliography. Otherwise, the style specified by a previous ibliographystyle declaration is used. If no such declaration was given, the BibTeX style plain is used as a default.

Unless the package was loaded with the option printheadings the environment produces no heading. Normally, you have to provide your own heading using section* or a similar command.

Within a btSect environment one of the above commands can be used to define which bibliographical entries are included among those from the specified file-list databases. The tPrintCited command prints all references from file-list that have been somewhere cited in the document, tPrintNotCited prints those that have not been cited, and tPrintAll prints all entries in the BibTeX database files.

The following example shows the basic concepts using two topics: “TeX related” and “Juridical” literature. The first bibliography uses the default plain style; for the second bibliography we explicitly specified the BibTeX style abbrv (this is meant as an illustration—mixing styles is usually a bad idea). As you can see, if you specify numerical BibTeX styles, bibtopic automatically uses consecutive numbers throughout all bibliographies, to ensure that the references in the document are unique.

For every btSect environment, the bibtopic package generates a separate .aux file that by default is constructed from the base name of the source document (jobname) and a sequence number. You can change this naming scheme by redefining hebtauxfile using the counter btauxfile to automatically obtain a sequence number. For the book examples we used the following redefinition:

Bibliographic topics per logical unit

The bibtopic package is incompatible with chapterbib and bibunits. However, it provides the environment btUnit to confine the citations to logical units. Within such units the btSect environment can be used in the normal way, allowing for topic bibliographies by chapter or other unit. In that case all citations have to appear within such units (escaping citations, discussed on page 746, are not handled so you have to ensure that they do not happen). By default, numerical styles restart their numbering per unit (e.g., per article in a proceedings issue). If you want continuous numbering use the option unitcntnoreset.

Problem with nonsorting BibTeX styles

While bibtopic works with most BibTeX styles, there are some exceptions. The most important one is that it does not work as expected with “unsorted” styles (e.g., unsrt). If such a style is used, then the order in the bibliography is determined by the order in the BibTeX database file and not by the order of citation in the document. If the latter order is required, you should use the multibib package described in the next section.

The bibtopic package is compatible with most other packages that provide extensions to the citation mechanism, including cite, natbib, and jurabib. There are some restrictions with respect to the production of the bibliography lists. For example, hooks to influence the layout as provided by natbib or jurabib may not be functional. Details are given in the package documentation.

There are advantages and disadvantages with either method. With multibib, different types of citations are clearly marked already in the source document. As a consequence, however, moving a citation from one bibliography to a different one in a consistent manner requires changes to the document in various places. In contrast, with bibtopic it merely requires moving the corresponding database entry from one file to another. On the other hand, bibtopic often requires tailored .bib files for each new document, while with multibib one can use generally available collections of BibTeX database files.

Recent versions of multibib are compatible with most other packages that provide extensions to the cite mechanisms, including cite, jurabib, and natbib. Moreover, the package provides a general interface which allows to add arbitrary extensions of cite commands to be recognized by multibib.

The ewcites declaration defines an additional set of citation commands for a new type of citations. The heading for the additional bibliography listing is title. Once this declaration is given the four additional commands are available for use. The command cite 〈type〉, like cite, generates a citation within the text and its corresponding reference appears in the bibliography listing for the new type. Similarly, ocite 〈type〉 adds a citation to the type bibliography without appearing in the text. The corresponding bibliography appears at the point where the ibliography 〈type〉 command is given, and the BibTeX style used for this bibliography is defined with ibliographystyle 〈type〉. An example is shown below.

The ewcites declaration can be used several times, thereby creating additional citation types. It is limited only by the number of output files that can be used simultaneously by TeX. The .aux file written for communication with BibTeX has the name 〈type〉.aux. For this reason one has to be a bit careful when selecting the type in the first argument to ewcites, to avoid overwriting other .aux files.

For numerical citation styles the references are by default numbered sequentially over all bibliographies to avoid ambiguous references. When using the option resetlabels, each bibliography restarts the numbering.