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