diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.ltx | 243 |
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} |