1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
%
% chapterbib.ltx Manual for chapterbib.sty
%
%
% Copyright (c) 1993-2010 by Donald Arseneau
%
% Version 1.16 (5-Sep-2010)
%
\documentclass[12pt,a4paper]{ltxdoc}
\setcounter{secnumdepth}{4}
\renewcommand\theparagraph{\arabic{paragraph}}
\newcommand\snugger{\vspace{-7pt}}
\MakeShortVerb{\"}
\hyphenpenalty=500
\sloppy
\setlength\parskip{2pt}
\raggedbottom
\title{chapterbib\\ multiple bibliographies in \LaTeX}
\author{Donald Arseneau\\ asnd@triumf.ca}
\date{2010/09/05}
\begin{document}
\maketitle
\begin{footnotesize}
\noindent Chapterbib is copyright \copyright\ 1989--2010 by
Niel Kempson and Donald Arseneau.\\
The package (chapterbib.sty) and this documentation (chapterbib.ltx,
chapterbib.pdf) may be freely transmitted, reproduced, or modified
for any purpose provided that the copyright notice is left intact.
(Small excerpts may of course be taken and used without any restriction.)
\par
\end{footnotesize}
\section*{Introduction}
The chapterbib package facilitates multiple bibliographies in a
\LaTeX\ document, including items \cs{cite}d (cited) in more than
one bibliography. Despite the name `chapterbib',
the \emph{bibliographies are for each included file}, not necessarily
for each chapter, although a bibliography per chapter is the usual
application. The main point is to allow you to use \BibTeX: Each
included file should have its own \cs{bibliographystyle} and
\cs{bibliography} commands, and you should run bibtex on each included
file separately rather than on the main or root file.
Chapterbib also provides the environment |cbunit|, and the command
\cs{cbinput} to allow multiple bibliographies without using \cs{include}
(see item~\ref{cbinput}).
There are two added hooks, \cs{citeform} and \cs{citepunct}, which you can
redefine to customize the formatting of each entry in a citation list,
and the declaration \cs{CitationPrefix} to use in preference to \cs{citeform}
for numbering-by-chapter.
Alternative packages: bibunits, biblatex.
\clearpage
\section*{Usage, Restrictions, and Options}
\paragraph{Normal use: } \leavevmode \label{normaluse}% 1.
Put \cs{bibliographystyle} and \cs{bibliography} commands in
each \cs{include}d file. Run \LaTeX; run \BibTeX\ on each included file;
run \LaTeX; run \LaTeX.
\snugger\paragraph{Whole bibliography: } \label{whole} % 2.
With chapterbib, the \cs{bibliography} and |\bibliography|\-|style|
commands are not normally used in the root file, only in files that
have been \cs{include}d. To have a whole-document bibliography, see
items \ref{separate}--\ref{duplicate}, depending on which style of
whole-document bib.
\snugger\paragraph{Without \textbackslash include: } \label{cbinput} % 3.
If you can't use \cs{include} because a new section must start below the
preceding bibliography on the same page (odd format!), then you can
use |\begin{cbunit}|\dots|\end{cbunit}| (for everything in one file)
or \cs{cbinput}, with a |thebibliography| environment in each unit
or input file.
To use \BibTeX, input separate files using \cs{cbinput}; at first use
the package or global option |[draft]|, run \LaTeX\ on the document,
then \BibTeX\ on each file that was \cs{cbinput}; finally, remove
the |[draft]| option and run \LaTeX\ again (maybe twice to get page
references right). The |[draft]| option only affects the treatment
of \cs{cbinput}, not \cs{include} or |\begin{cbunit}|.
\snugger\paragraph{Package compatability: }\label{compatability} % 4.
Your preferred citation style (call it xxx.sty) may not work with
chapterbib at first, but it is easy to make it compatible:
In `xxx.sty' change every `|@\@citeb|' to `|@\@citeb\@extra@b@citeb|',
and insert the line\\[3pt]
\indent
|\@ifundefined{@extra@b@citeb}{\def\@extra@b@citeb{}}{}|\\[3pt]
somewhere (but not as a comment or as part of another definition!).
If the package also redefines \cs{bibcite} then you should change that
definition, replacing `|@#1|' with `|@#1\@extra@binfo|', and insert
\\[3pt]\indent
|\gdef\@extra@binfo{}|\\[3pt]
somewhere in the file. If the package defines a command that acts
similarly to \cs{bibcite} (being written to the aux file, and then
executed as the aux file is processed), then it should
have `|\@extra@binfo|' inserted in the same way.
Some citation packages deviate quite far from \LaTeX's own method
of organizing cite tags using `|b@\@citeb|'. The instructions above
catch such extensions as `|Y@\@citeb|', but not more radical differences.
In such cases, try contacting the author of the citation package.
If a citation style does not (re)define \cs{nocite}, then that command
would not be converted when you make the patches at `|@\@citeb|'.
Chapterbib will try to detect the presence of \cs{@extra@b@citeb}
in \cs{nocite} and insert it, but if that fails you may need to
redefine \cs{nocite} changing any `|@\@citeb|' to
`|@\@citeb\@extra@b@citeb|' in that sty file.
\snugger\paragraph{Sectionbib: }\label{sectionbib} % 5.
The report and book document classes usually treat the bibliography as
an unnumbered chapter (|\chapter*|), which is not so good for
bibliographies \emph{in} a chapter. You can specify\\[3pt]
\indent
|\usepackage[sectionbib]{chapterbib}| \\[3pt]
to convert your bibliographies from |\chapter*| to |\section*|, with an
entry in the table of contents and the page-header. A bibliography in
the root file remains as a |\chapter*|. The |[sectionbib]| option modifies
the existing |thebibliography| environment (or the \cs{bibsection}
command, if present already), so the other formatting in the bibliography
should remain unchanged. On the other hand, if you already have a
non-standard bibliography defined, or if you want them numbered, it
may be easier to redefine \cs{thebibliography} directly, without any
tricky modification of existing commands.
Alternatively, you can use the \cs{sectionbib} command directly in the
document preamble. It takes two parameters: the sectioning command, and
the name of the sectioning level. For instance, the |[sectionbib]| option
executes |\sectionbib{\section*}{section}|. Again, for the most control,
it is better to redefine \cs{thebibliography} entirely.
\snugger\paragraph{Overall separate bibliography: } \label{separate} %6.
If you want a completely unrelated bibliography in the root file, perhaps
for a general reading list, you can provide your own bibliography there
using the |thebibliography| environment. I don't suppose this will appeal
to \BibTeX\ users!
\snugger\paragraph{Overall bibliography: }\label{overall}% 7.
To have a cohesive bibliography for the whole document, plus individual
bibs in the chapters, put \cs{bibliography} commands in the included
chapters plus in the root file. Make sure the \cs{bibliographystyle}
for the overall bibliography appears \emph{first}, before any chapters
are included. Run \LaTeX; run \BibTeX\ on the root file; run \BibTeX\ on
each included file; run \LaTeX; run \LaTeX.
This produces an independent `overall' bibliography which only
makes sense for various `named' bibliography styles; a numbered style, or
one with any type of automatic enumeration (like Me2007a, Me2007b) will
give unrelated numbers in each bibliography and lead to confusion.
\BibTeX\ will complain about multiple \cs{bibdata} commands when it makes
the whole bibliography, but it should obey the first. If you don't
want to see any error messages from bibtex, or if you don't want to put
the main \cs{bibliographystyle} command first in the document, then use
|\usepackage[rootbib]{chapterbib}| when you run \LaTeX\ first; run
\BibTeX\ on the root file; change to |\usepackage{chapterbib}|; run
\LaTeX; run \BibTeX\ on each included file; run \LaTeX; run \LaTeX.
\snugger\paragraph{Chapter bibs gathered to end: }\label{gather} % 8.
To have a bibliography-by-chapter at the end instead of separate
bibs in the chapters, use |\usepackage[gather]{chapterbib}|, put
\cs{bibliography} commands in each file, and at the end of the main
file. Run \LaTeX\ as in item~\ref{normaluse}. You can control the
titling of the final bibliographies by defining \cs{FinalBibTitles},
such as\\[3pt]
\indent|\newcommand\FinalBibTitles|\\
\indent \indent |{References for Chapter \thechapter}|\\[3pt]
A similar effect may be achieved by re-defining \cs{FinalBibPrefix} as
\\[3pt] \indent
|\renewcommand\FinalBibPrefix{References for }|\\[3pt]
Even more control is achieved by redefining \cs{StartFinalBibs}.
The default definition is (like)
\begin{verbatim}
\newcommand{\StartFinalBibs}{%
\renewcommand{\bibname}{Bibliography for chapter n}}
\end{verbatim}
normally, but when using the [sectionbib] option it becomes
\begin{verbatim}
\newcommand{\StartFinalBibs}{\chapter*{\bibname}%
\addcontentsline{toc}{chapter}{\bibname}%
\@mkboth{\bibname}{\bibname}%
\renewcommand{\bibname}{Chapter n}}
\end{verbatim}
where the \cs{bibname} text is now provided by \cs{@auto@bibname},
which relies on bookkeeping and \cs{FinalBibPrefix}.
If your document class has neither section nor chapter, then you must
define \cs{StartFinalBibs} and also indicate the sectioning: for example,
if the main sectioning command in your document class is \cs{motif}:
\\[3pt]\indent
|\newcommand\CBMainSectioning{motif}|
\snugger\paragraph{Duplicate bibliographies at end: } \label{duplicate}% 9
To have bibliographies in each chapter \emph{plus} a
bibliography-by-chapter at the end, follow item~\ref{gather},
but declare\\[3pt]
\indent |\usepackage[duplicate]{chapterbib}|\\
\indent (or |\usepackage[duplicate,sectionbib]{chapterbib}|).
\snugger\paragraph{Babel: } % 10
If you use Babel, load chapterbib before babel.
\section*{Formatting extensions}
\snugger\paragraph*{\textbackslash citeform}
Normally, the citations are formatted as given, but you can define
\cs{citeform} (with one parameter) to reformat every citation.
Some possibilities:\\[3pt]
\quad |\renewcommand\citeform[1]{\romannumeral 0#1}| \hfill [iv,x]\\
\quad |\renewcommand\citeform[1]{(#1)} | \hfill [(3),(4),(7)]\\[3pt]
If you change \cs{citeform}, you should really define \cs{@biblabel} to match.
A not-so-good way to provide a chapter-number prefix is\\[3pt]
\indent |\renewcommand\citeform[1]{\thechapter.#1}| \\[3pt]
This partially works, but has only limited applicability: it does not
work with cites in the front-matter (TOC, LOF) or with hyperref.
\snugger\paragraph*{\textbackslash CitationPrefix}
Instead, there is a \cs{CitationPrefix} command to apply a prefix to the
citation numbers (or names) in the bibliographies and \cs{cite} commands
for the included files. Use it by declaring something like\\[3pt]
\indent |\CitationPrefix{\thechapter.}| \\[3pt]
in the preamble. The prefix will be applied to all the chapter-bibs
but will not be used in an overall (root) bibliography, if you have one.
This not only affects the formatting but the actual citation, therefore
it immediately applies to \cs{bibitem} (no need to change \cs{@biblabel})
and works with hyperref. (The \cs{CitationPrefix} mechanism may be
prone to conflicts with other packages.)
\snugger\paragraph*{\textbackslash citepunct}
The \cs{citepunct} command gives the punctuation (comma-penalty-space)
between items in the \cs{cite} list, and you can redefine it.
\end{document}
|
