Le package bibunits

Thorsten Hansen

hansen@neuro.informatik.uni-ulm.de

v2.1 1999/10/22

Résumé Le package bibunits permet la création de bibliographies séparées pour différentes unités (parties) du texte. Les unités peuvent être des chapitre, des sections ou bien des environements bibunit. Le package place les citations de chaque unité de texte dans un fichier auxiliaire distinct, devant être traité par BibTEX. La même citation peut se trouver dans plus d’une bibliographie. Une bibliographie globale peut également apparaître dans le document et contenir des citations déjà présentes. Le package est compatible avec overcite et natbib. Il est basé sur le style bibunits de José Alberto Fernández.

1 Notice d’utilisation

\bibliographyunit  Utilisez \bibliographyunit[⟨unité⟩], où ⟨unité⟩ peut être \chapter ou

\section pour préciser le niveau de division du document pour lequel les références doivent être générées, c’est-à-dire pour chaque chapitre ou pour chaque section. Utilisez \bibliographyunit sans argument pour désactiver cette commande. Par défaut \bibliographyunit est désactivée.

\bibliography Vous pouvez une bibliographie globale comme d’habitude avec les commandes

\bibliographystyle  \bibliography[⟨BibTeX files⟩] et \bibliographystyle[⟨style⟩]. Si

\bibliographyunit est active, ces commandes précisent également les fichiers BibTEX à utiliser par défaut dans les bibliographies locales.

\bibliography* QUand \bibliographyunit est active, vous pouvez utiliser les formes étoilées

\bibliographystyle*  \bibliography*{⟨BibTeX files⟩} et \bibliographystyle*{⟨style⟩} pour préci-

ser les fichiers à utiliser par défaut au niveau des bibliographies locales uniquement. Ces commandes ne produisent aucune information pour la bibliographie générale.

bibunit  L’environnement \begin{bibunit}[⟨style⟩]

The environment \begin{bibunit}[⟨style⟩] allows the creation of a unit while \bibliographyunit is not active. The optional parameter ⟨style⟩ specifies a style for the bibliography different from the default, if any. Warning : The use of this environment while \bibliographyunit is active can produce strange results. Note that default style and BibTEX files only exist if specified while \bibliographyunit is active.

\cite* Use \cite and \nocite to generate citations that appear in the local biblio-

\nocite*

graphy. Use \cite* and \nocite* inside a unit to generate citations for both the local and global bibliography.

\putbib You must insert the command \putbib[⟨BibTeX files⟩] before the end of each unit at the location where you want the bibliography to be inserted. If the optional argument is omited, \putbib uses the default BibTEX files, if any.

1.1 BibTEX processing

For each bibunit, in sequence, there is now a corresponding file bu⟨i⟩.aux that needs to be compiled through BibTEX. Suppose your document has ⟨n⟩ different bibunits, you must now invoke BibTEX on bu1, …, bu⟨n⟩. This can be done by a csh-script.

    #!/bin/csh
    foreach auxfile (bu*.aux)
      echo bibtex `basename $auxfile .aux`
      bibtex `basename $auxfile .aux`
    end

If by some strange coincidence you have named some of your files bu⟨i⟩.aux, you have to redefine the internal command \@bibunitname, otherwise your files will be overwritten. To get for your document foo.tex filenames foo.⟨i⟩.aux as for the first version of bibunits, you can redefine the internal macro \@bibunitname.

    \makeatletter
    \renewcommand{\@bibunitname}{\jobname.\the\@bibunitauxcnt}
    \makeatother

If you also want a global bibliography for your document foo.tex, the file foo.aux needs to be compiled through BibTEX as well.

1.2 Limitations

– Package natbib permanently issues a warning ‘Citation(s) may have changed. Rerun to get citations correct.’, when the position of a reference in the global bibliography is different from its position in the last local bibliography. This warning can be ignored.

– When package natbib is loaded, \cite* has the meaning as defined by natbib, namely to force full citation of multiple authors. To get the behavior as defined by bibunits (without natbib), use an accompanying \nocite outside of a bibunit.

2 Examples

2.1 Bibunits by the bibunit environment

In the first example, two bibliographies are generated, the first using the BibTEX file texlit.bib and the style plain, the second using the BibTEX file

lit.bib and the style abbrv.
   \documentclass{article}
   \usepackage{bibunits}
   \begin{document}
   \begin{bibunit}[plain]
     some text \cite{lamport:1994} more text more citations
     \putbib[texlit]
   \end{bibunit}
   some text between the units
   \begin{bibunit}[abbrv]
     some text \cite{gnu:1998} more text more citations
     \putbib[lit]
   \end{bibunit}
   \end{document}

If all bibunits use the same BibTEX files and style, you can specify defaults and omit the optional arguments of the bibunit environment and the \putbib macro. In the second example, a default BibTEX file texlit.bib and a default style abbrv is defined. Note that you have to activate bibliographyunits with the command

\bibliographyunit[\section] (\chapter would also work) before you can spe-

cify the defaults, and afterwards you have to deactivate bibliographyunits with the command \bibliographyunit before you can use the bibunit environment.

    : same as in the previous example
   \begin{document}
   \bibliographyunit[\section]
   \bibliography*{texlit}
   \bibliographystyle*{plain}
   \bibliographyunit
   \begin{bibunit}
     some text \cite{lamport:1994} more text more citations
     \putbib
   \end{bibunit}
   some text between the units
   \begin{bibunit}
     some text \cite{knuth:1991} more text more citations
     \putbib
   \end{bibunit}
   \end{document}

If you use the class article, the heading of the bibliography has the same size as a section, which might be too large, especially if you have bibunits within sections or even subsections. In this case you may want to change the bibliography heading to have the same appearance as a subsection.

   \let\stdthebibliography\thebibliography

   \renewcommand{\thebibliography}{%
     \let\section\subsection
     \stdthebibliography}

Note that other classes may use other formatting instead of section for the bibliography heading. In this case the definition has to be changed accordingly, e.g., for the book class, where bibliography headings appear at the chapter level,

let \chapter to \subsection.
    \let\stdthebibliography\thebibliography
    \renewcommand{\thebibliography}{%
       \let\chapter\subsection
       \stdthebibliography}

2.2 Bibunits by chapters or sections

You can also define bibliographies for every chapter or section. In this case, the redefinition of \thebibliography is essential for the proper behavior of the bibunits package. The reason is quite simple : if you create bibliographies for every section, and \thebibliography also appears at the section level, a new unit is opened by \thebibliography, and the information of the previous unit is no longer available. (More technically : The auxiliary file of the previous unit is closed, and the replacement text for the citation which is generated inside \thebibliography cannot be written to this file. Instead, it is written to the global .aux file.)

The next example corresponds to the first example of the previous section with different BibTEX files and styles. Note that you have to specify the \bibliographystyle* before the corresponding section.

   \documentclass{article}
   \usepackage{bibunits}
   \let\stdthebibliography\thebibliography
   \renewcommand{\thebibliography}{%
     \let\section\subsection
     \stdthebibliography}
   \begin{document}
   \bibliographyunit[\section]
   \bibliographystyle*{plain}
   \section{First section}
     some text \cite{lamport:1994} more text more citations
     \putbib[texlit]
   some text between the units
   \bibliographystyle*{abbrv}
   \section{Second and last section}
     some text \cite{gnu:1998} more text more citations
     \putbib[lit]

   \end{document}

You can also use the same BibTEX file and style for all units.

    : same as in the previous example
   \begin{document}
   \bibliographyunit[\section]
   \bibliography*{texlit}
   \bibliographystyle*{plain}
   \section{First section}
     some text \cite{lamport:1994} more text more citations
     \putbib
   some text between the units
   \section{Second and last section}
     some text \cite{knuth:1991} more text more citations
     \putbib
   \end{document}

In all four examples, one can specify a global bibliography and its style with the usual L^{A}TEX commands. Citations for the global bibliography are entered using \cite and \nocite commands while outside a unit or using \cite* and \nocite* while inside a unit. The starred forms generate citations also for the local unit. Thus it is not possible to generate citations only for the global bibliography while inside a unit (which seems to be a reasonable restriction). Note that if \bibliographyunit is active, and you use a global bibliography, and you use the same BibTEX file and style for all (local as well as global) bibliographies, then

the \bibliography* and \bibliographystyle* commands are not necessary. In

this case proper defaults for the local bibliographies are specified by the commands \bibliography and \bibliographystyle, too. Note that a second run of L^{A}TEX is necessary before BibTEX processing, in case that the global bibliography has its usual place at the end of the document.

3 Changes

Changes from v2.0 to v2.1

– overcite compatibility.

– natbib compatibility.

– Local version of \cite declared robust.

Consequently, \cite can be used, e.g., inside \caption of a \figure environment, and spaces can be used in the argument of a \cite command (to separate multiple citations).

Changes from v1.0 to v2.0

– The same referenced item can be used in more than one bibliography.

– The package can be used on systems where filenames of three items are not allowed. Instead of creating files \jobname.⟨i⟩.aux, the files are named bu⟨i⟩.aux. A filename of three items causes problems on non-UNIX-systems like MS-DOS, CMS or VMS, as reported, e.g., in the L^{A}TEX Companion.

– Auxiliary files are created only for bibunits which contain cite commands. Imagine, you want to specify bibliographies for sections using \bibliographyunit[\section], but only a small number of, say, ten sections of your total of 100 sections have cite commands. Formerly, 100 auxiliary files have been created by bibunits, now only ten. This is faster and makes both manual and automatic processing by BibTEX easier.

– The default styles and files are defined globally, so that the information is already present at the first run of L^{A}TEX. Formerly, default styles and files have been written only to the global auxiliary file, so that a second run of L^{A}TEX was necessary before BibTEX processing.

– Extra spaces are no longer introduced.

– Upgrade to L^{A}TEX 2ε.

4 Acknowledgements

The author thanks José Alberto Fernández for the coding of bibunits v1.0 ; Werner Jürgens for the hint on how to suppress unwanted spaces ; Andrew E. Schulman for an early version of the natbib compatibility patch.

Change History

Version 1.0 by José Alberto Fernández, Version 1.0a till 2.1 by Thorsten Hansen. Version numbers suffixed with characters have not been released.

v1.0

General : Initial L^{A}TEX 2.09 version. 1 v1.0a

General : The same cited item can occur in more than one bibliography. . . . . . . . . . . . . . . . . . . 1

v1.0b General : Auxiliary files are created only for bibunits which contain cite commands. . . . . . . . . . . . . 1

v1.0c

General : Upgrade to L^{A}TEX 2ε. … 1 v2.0

General : Documentation. . . . . . . 1 v2.1

General : Documentation. . . . . . . 1