summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cite/chapterbib.ltx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/cite/chapterbib.ltx
Initial commit
Diffstat (limited to 'macros/latex/contrib/cite/chapterbib.ltx')
-rw-r--r--macros/latex/contrib/cite/chapterbib.ltx243
1 files changed, 243 insertions, 0 deletions
diff --git a/macros/latex/contrib/cite/chapterbib.ltx b/macros/latex/contrib/cite/chapterbib.ltx
new file mode 100644
index 0000000000..b134ac1b17
--- /dev/null
+++ b/macros/latex/contrib/cite/chapterbib.ltx
@@ -0,0 +1,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}