Debian Codegraph @

texmf-dist/doc/latex/natbib/natnotes.tex

raw
1 %%
2 %% This is file `natnotes.tex',
3 %% generated with the docstrip utility.
4 %%
5 %% The original source files were:
6 %%
7 %% natbib.dtx (with options: `notes')
8 %% =============================================
9 %% IMPORTANT NOTICE:
10 %%
11 %% This program can be redistributed and/or modified under the terms
12 %% of the LaTeX Project Public License Distributed from CTAN
13 %% archives in directory macros/latex/base/lppl.txt; either
14 %% version 1 of the License, or any later version.
15 %%
16 %% This is a generated file.
17 %% It may not be distributed without the original source file natbib.dtx.
18 %%
19 %% This is a Reference Sheet for natbib. It consists of excerpts from the
20 %% original source file.
21 %%
22 %% For more details, LaTeX the source natbib.dtx.
23 %% ==============================================
24 %% Copyright 1993-2010 Patrick W Daly
25 %% Max-Planck-Institut f\"ur Sonnensystemforschung
26 %% Max-Planck-Str. 2
27 %% D-37191 Katlenburg-Lindau
28 %% Germany
29 %% E-mail: [email protected]
30 \NeedsTeXFormat{LaTeX2e}
31 \def\DescribesFile#1 [#2 #3 #4]
32 {\def\filename{#1}\def\filedate{#2}\def\fileversion{#3}}
33 \DescribesFile{natbib}
34 [2010/09/13 8.31b (PWD, AO)]
35 \documentclass{article}
36
37 \setlength{\parindent}{0pt}
38 \setlength{\parskip}{1ex}
39 \setlength{\textwidth}{\paperwidth}
40 \addtolength{\textwidth}{-2in}
41 \setlength{\oddsidemargin}{0pt}
42 \setlength{\textheight}{\paperheight}
43
44 \addtolength{\textheight}{-\headheight}
45 \addtolength{\textheight}{-\headsep}
46 \addtolength{\textheight}{-\footskip}
47 \addtolength{\textheight}{-2in}
48 \makeatletter
49 \def\@listI{\leftmargin\leftmargini
50 \topsep\z@ \parsep\parskip \itemsep\z@}
51 \let\@listi\@listI
52 \@listi
53 \makeatother
54 \newcommand{\head}[1]{\subsubsection*{#1}}
55
56 \pagestyle{headings}
57 \markright{Reference sheet: \texttt{natbib}}
58
59 \usepackage{shortvrb}
60 \MakeShortVerb{\|}
61
62 \begin{document}
63 \thispagestyle{plain}
64
65 \newcommand{\btx}{\textsc{Bib}\TeX}
66 \newcommand{\thestyle}{\texttt{\filename}}
67 \begin{center}{\bfseries\Large
68 Reference sheet for \thestyle\ usage}\\
69 \large(Describing version \fileversion\ from \filedate)
70 \end{center}
71
72 \begin{quote}\slshape
73 For a more detailed description of the \thestyle\ package, \LaTeX\ the
74 source file \thestyle\texttt{.dtx}.
75 \end{quote}
76 \head{Overview}
77 The \thestyle\ package is a reimplementation of the \LaTeX\ |\cite| command,
78 to work with both author--year and numerical citations. It is compatible with
79 the standard bibliographic style files, such as \texttt{plain.bst}, as well as
80 with those for \texttt{harvard}, \texttt{apalike}, \texttt{chicago},
81 \texttt{astron}, \texttt{authordate}, and of course \thestyle.
82
83 \head{Loading}
84 Load with |\usepackage[|\emph{options}|]{|\thestyle|}|. See list of
85 \emph{options} at the end.
86
87 \head{Replacement bibliography styles}
88 I provide three new \texttt{.bst} files to replace the standard \LaTeX\
89 numerical ones:
90 \begin{quote}\ttfamily
91 plainnat.bst \qquad abbrvnat.bst \qquad unsrtnat.bst
92 \end{quote}
93 \head{Basic commands}
94 The \thestyle\ package has two basic citation commands, |\citet| and
95 |\citep| for \emph{textual} and \emph{parenthetical} citations, respectively.
96 There also exist the starred versions |\citet*| and |\citep*| that print
97 the full author list, and not just the abbreviated one.
98 All of these may take one or two optional arguments to add some text before
99 and after the citation.
100 \begin{quote}
101 \begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
102 |\citet{jon90}| & Jones et al. (1990)\\
103 |\citet[chap.~2]{jon90}| & Jones et al. (1990, chap.~2)\\[0.5ex]
104 |\citep{jon90}| & (Jones et al., 1990)\\
105 |\citep[chap.~2]{jon90}| & (Jones et al., 1990, chap.~2)\\
106 |\citep[see][]{jon90}| & (see Jones et al., 1990)\\
107 |\citep[see][chap.~2]{jon90}| & (see Jones et al., 1990, chap.~2)\\[0.5ex]
108 |\citet*{jon90}| & Jones, Baker, and Williams (1990)\\
109 |\citep*{jon90}| & (Jones, Baker, and Williams, 1990)
110 \end{tabular}
111 \end{quote}
112 \head{Multiple citations}
113 Multiple citations may be made by including more than one
114 citation key in the |\cite| command argument.
115 \begin{quote}
116 \begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
117 |\citet{jon90,jam91}| & Jones et al. (1990); James et al. (1991)\\
118 |\citep{jon90,jam91}| & (Jones et al., 1990; James et al. 1991)\\
119 |\citep{jon90,jon91}| & (Jones et al., 1990, 1991)\\
120 |\citep{jon90a,jon90b}| & (Jones et al., 1990a,b)
121 \end{tabular}
122 \end{quote}
123
124 \head{Numerical mode}
125 These examples are for author--year citation mode. In numerical mode, the
126 results are different.
127 \begin{quote}
128 \begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
129 |\citet{jon90}| & Jones et al. [21]\\
130 |\citet[chap.~2]{jon90}| & Jones et al. [21, chap.~2]\\[0.5ex]
131 |\citep{jon90}| & [21]\\
132 |\citep[chap.~2]{jon90}| & [21, chap.~2]\\
133 |\citep[see][]{jon90}| & [see 21]\\
134 |\citep[see][chap.~2]{jon90}| & [see 21, chap.~2]\\[0.5ex]
135 |\citep{jon90a,jon90b}| & [21, 32]
136 \end{tabular}
137 \end{quote}
138 \head{Suppressed parentheses}
139 As an alternative form of citation, |\citealt| is the same as |\citet| but
140 \emph{without parentheses}. Similarly, |\citealp| is |\citep| without
141 parentheses.
142
143 The |\citenum| command prints the citation number, without parentheses, even
144 in author--year mode, and without raising it in superscript mode. This is
145 intended to be able to refer to citation numbers without superscripting them.
146
147 \begin{quote}
148 \begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
149 |\citealt{jon90}| & Jones et al.\ 1990\\
150 |\citealt*{jon90}| & Jones, Baker, and Williams 1990\\
151 |\citealp{jon90}| & Jones et al., 1990\\
152 |\citealp*{jon90}| & Jones, Baker, and Williams, 1990\\
153 |\citealp{jon90,jam91}| & Jones et al., 1990; James et al., 1991\\
154 |\citealp[pg.~32]{jon90}| & Jones et al., 1990, pg.~32\\
155 |\citenum{jon90}| & 11\\
156 |\citetext{priv.\ comm.}| & (priv.\ comm.)
157 \end{tabular}
158 \end{quote}
159 The |\citetext| command
160 allows arbitrary text to be placed in the current citation parentheses.
161 This may be used in combination with |\citealp|.
162 \head{Partial citations}
163 In author--year schemes, it is sometimes desirable to be able to refer to
164 the authors without the year, or vice versa. This is provided with the
165 extra commands
166 \begin{quote}
167 \begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
168 |\citeauthor{jon90}| & Jones et al.\\
169 |\citeauthor*{jon90}| & Jones, Baker, and Williams\\
170 |\citeyear{jon90}| & 1990\\
171 |\citeyearpar{jon90}| & (1990)
172 \end{tabular}
173 \end{quote}
174 \head{Forcing upper cased names}
175 If the first author's name contains a \textsl{von} part, such as ``della
176 Robbia'', then |\citet{dRob98}| produces ``della Robbia (1998)'', even at the
177 beginning of a sentence. One can force the first letter to be in upper case
178 with the command |\Citet| instead. Other upper case commands also exist.
179 \begin{quote}
180 \begin{tabular}{rl@{\quad$\Rightarrow$\quad}l}
181 when & |\citet{dRob98}| & della Robbia (1998) \\
182 then & |\Citet{dRob98}| & Della Robbia (1998) \\
183 & |\Citep{dRob98}| & (Della Robbia, 1998) \\
184 & |\Citealt{dRob98}| & Della Robbia 1998 \\
185 & |\Citealp{dRob98}| & Della Robbia, 1998 \\
186 & |\Citeauthor{dRob98}| & Della Robbia
187 \end{tabular}
188 \end{quote}
189 These commands also exist in starred versions for full author names.
190
191 \head{Citation aliasing}
192 Sometimes one wants to refer to a reference with a special designation,
193 rather than by the authors, i.e. as Paper~I, Paper~II. Such aliases can be
194 defined and used, textual and/or parenthetical with:
195 \begin{quote}
196 \begin{tabular}{lcl}
197 |\defcitealias{jon90}{Paper~I}|\\
198 |\citetalias{jon90}| & $\Rightarrow$ & Paper~I\\
199 |\citepalias{jon90}| & $\Rightarrow$ & (Paper~I)
200 \end{tabular}
201 \end{quote}
202 These citation commands function much like |\citet| and |\citep|: they may
203 take multiple keys in the argument, may contain notes, and are marked as
204 hyperlinks.
205 \head{Selecting citation style and punctuation}
206 Use the command |\setcitestyle| with a list of comma-separated
207 keywords (without spaces) as argument.
208 \begin{itemize}
209 \item
210 Citation mode: |authoryear| or |numbers| or |super|
211 %^^A \ifNAT@numbers \ifNAT@super
212 \item
213 Braces: |round| or |square| or |open={|\emph{char}|},close={|\emph{char}|}|
214 %^^A \NAT@open \NAT@close
215 \item
216 Between citations: |semicolon| or |comma| or |citesep={|\emph{char}|}|
217 %^^A \NAT@sep
218 \item
219 Between author and year: |aysep={|\emph{char}|}|
220 %^^A \NAT@aysep
221 \item
222 Between years with common author: |yysep={|\emph{char}|}|
223 %^^A \NAT@yrsep
224 \item
225 Text before post-note: |notesep={|\emph{text}|}|
226 %^^A \NAT@cmt
227 \end{itemize}
228 Defaults are |authoryear|, |round|, |comma|, |aysep={;}|, |yysep={,}|,
229 |notesep={, }|
230
231 Example~1, |\setcitestyle{square,aysep={},yysep={;}}| changes the author--year
232 output of
233 \begin{quote}
234 |\citep{jon90,jon91,jam92}|
235 \end{quote}
236 into [Jones et al. 1990; 1991, James et al. 1992].
237
238 Example~2, |\setcitestyle{notesep={; },round,aysep={},yysep={;}}| changes the output of
239 \begin{quote}
240 |\citep[and references therein]{jon90}|
241 \end{quote}
242 into (Jones et al. 1990; and references therein).
243
244 \head{Other formatting options}
245 Redefine |\bibsection| to the desired sectioning command for introducing
246 the list of references. This is normally |\section*| or |\chapter*|.
247
248 Redefine |\bibpreamble| to be any text that is to be printed after the heading but
249 before the actual list of references.
250
251 Redefine |\bibfont| to be a font declaration, e.g.\ |\small| to apply to
252 the list of references.
253
254 Redefine |\citenumfont| to be a font declaration or command like |\itshape|
255 or |\textit|.
256
257 Redefine |\bibnumfmt| as a command with an argument to format the numbers in
258 the list of references. The default definition is |[#1]|.
259
260 The indentation after the first line of each reference is given by
261 |\bibhang|; change this with the |\setlength| command.
262
263 The vertical spacing between references is set by |\bibsep|; change this with
264 the |\setlength| command.
265
266 \head{Automatic indexing of citations}
267 If one wishes to have the citations entered in the \texttt{.idx} indexing
268 file, it is only necessary to issue |\citeindextrue| at any point in the
269 document. All following |\cite| commands, of all variations, then insert
270 the corresponding entry to that file. With |\citeindexfalse|, these
271 entries will no longer be made.
272
273 \head{Use with \texttt{chapterbib} package}
274
275 The \thestyle\ package is compatible with the \texttt{chapterbib} package
276 which makes it possible to have several bibliographies in one document.
277
278 The package makes use of the |\include| command, and each |\include|d file
279 has its own bibliography.
280
281 The order in which the \texttt{chapterbib} and \thestyle\ packages are loaded
282 is unimportant.
283
284 The \texttt{chapterbib} package provides an option \texttt{sectionbib}
285 that puts the bibliography in a |\section*| instead of |\chapter*|,
286 something that makes sense if there is a bibliography in each chapter.
287 This option will not work when \thestyle\ is also loaded; instead, add
288 the option to \thestyle.
289
290 Every |\include|d file must contain its own
291 |\bibliography| command where the bibliography is to appear. The database
292 files listed as arguments to this command can be different in each file,
293 of course. However, what is not so obvious, is that each file must also
294 contain a |\bibliographystyle| command, with possibly differing arguments.
295
296 As of version~8.0, the citation style, including mode (author--year or
297 numerical) may also differ between chapters. The |\setcitestyle| command
298 can be issued at any point in the document, in particular in different
299 chapters.
300 \head{Sorting and compressing citations}
301 Do not use the \texttt{cite} package with \thestyle; rather use one of the
302 options \texttt{sort}, \texttt{compress}, or \texttt{sort\&compress}.
303
304 These also work with author--year citations, making multiple citations appear
305 in their order in the reference list.
306
307
308 \head{Merged Numerical References}
309 Do not use the \texttt{mcite} package with \thestyle; rather use the package option \texttt{merge}.
310
311
312 With this option in effect, citation keys within a multiple |\citep| command
313 may contain a leading * that causes them to be merged in the bibliography
314 together with the previous citation as a single entry with a single reference
315 number. For example, |\citep{feynmann,*salam,*epr}| produces a single number,
316 and all three references are listed in the bibliography under one entry with
317 that number.
318
319 The \texttt{elide} option also activates the merging features, but also sees
320 to it that common parts of the merged references (e.g., authors) are not
321 repeated but are written only once in the single bibliography entry.
322
323 The \texttt{mcite} option turns off the merging and eliding features, but
324 allows the special syntax (the * and optional inserted texts) to be ignored.
325
326 These functions are available only to numerical-mode citations, and only when
327 used parenthetically, similar to the restrictions on \texttt{sort} and
328 \texttt{compress}.
329
330 They also require special \texttt{.bst} files, as provided for example by the
331 American Physical Society for their REV\TeX\ class.
332 \head{Long author list on first citation}
333 Use option \texttt{longnamesfirst} to have first citation automatically give
334 the full list of authors.
335
336 Suppress this for certain citations with |\shortcites{|\emph{key-list}|}|,
337 given before the first citation.
338
339 \head{Local configuration}
340 Any local recoding or definitions can be put in \thestyle\texttt{.cfg} which
341 is read in after the main package file.
342
343 \head{Options that can be added to \texttt{\char`\\ usepackage}}
344 \begin{description}
345 \item[\ttfamily round] (default) for round parentheses;
346 \item[\ttfamily square] for square brackets;
347 \item[\ttfamily curly] for curly braces;
348 \item[\ttfamily angle] for angle brackets;
349 \item[\ttfamily semicolon] (default) to separate multiple citations with
350 semi-colons;
351 \item[\ttfamily colon] the same as \texttt{semicolon}, an earlier mistake in
352 terminology;
353 \item[\ttfamily comma] to use commas as separators;
354 \item[\ttfamily authoryear] (default) for author--year citations;
355 \item[\ttfamily numbers] for numerical citations;
356 \item[\ttfamily super] for superscripted numerical citations, as in
357 \textsl{Nature};
358 \item[\ttfamily sort] orders multiple citations into the sequence in
359 which they appear in the list of references;
360 \item[\ttfamily sort\&compress] as \texttt{sort} but in addition multiple
361 numerical citations are compressed if possible (as 3--6, 15);
362 \item[\ttfamily compress] to compress without sorting, so compression only
363 occurs when the given citations would produce an ascending sequence of
364 numbers;
365 \item[\ttfamily longnamesfirst] makes the first citation of any reference
366 the equivalent of the starred variant (full author list) and subsequent
367 citations normal (abbreviated list);
368 \item[\ttfamily sectionbib] redefines |\thebibliography| to issue
369 |\section*| instead of |\chapter*|; valid only for classes with a
370 |\chapter| command; to be used with the \texttt{chapterbib} package;
371 \item[\ttfamily nonamebreak] keeps all the authors' names in a citation on
372 one line; causes overfull hboxes but helps with some \texttt{hyperref}
373 problems;
374 \item[\ttfamily merge] to allow the * prefix to the citation key,
375 and to merge such a citation's reference with that of the previous
376 citation;
377 \item[\ttfamily elide] to elide common elements of merged references, like
378 the authors or year;
379 \item[\ttfamily mcite] to recognize (and ignore) the merging syntax.
380 \end{description}
381 \end{document}
382 %%
383 %% End of Reference Sheet file
384 %%
385 %%
386 %% End of file `natnotes.tex'.