Debian Codegraph @

texmf-dist/doc/latex/cite/chapterbib.ltx

raw
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}