Debian Codegraph @

texmf-dist/doc/latex/natbib/README.v831b

raw
1 NATBIB Package
2 Current Version: 8.31b from 2010/09/13
3
4 See list of changes below
5
6 This is the natbib package for handling both author-year and numerical
7 BibTeX styles.
8
9 Manifest:- The natbib package contains the following files:
10 ~~~~~~~~~~
11 natbib.dtx -- Documented source file that may be LaTeXed to get the
12 detailed description and/or coding documentation.
13
14 May be docstripped with option `package,all' to get the
15 natbib.sty package file, or processed with natbib.ins.
16
17 natbib.ins -- A docstrip batch job to extract natbib.sty and natnotes.tex
18 from the source file natbib.dtx.
19 Simply TeX or LaTeX this file.
20
21 This file is embedded in natbib.dtx. If it is missing, then LaTeXing
22 natbib.dtx will extract it.
23
24 plainnat.bst -- Replacements for plain.bst, abbrv.bst, unsrt.bst, the
25 abbrvnat.bst standard BibTeX bib style files. These replacements
26 unsrtnat.bst permit both numerical and author-year citations
27
28 bibentry.dtx -- Documented source file for the bibentry package, defines
29 \bibentry{key} command that places the bibliography entry
30 in the text. Useful for descriptive bibliographies.
31
32 bibentry.ins -- The installation file for bibentry. Just TeX or LaTeX it.
33
34 Generation:- Simply run TeX or LaTeX on natbib.ins, which extracts
35 ~~~~~~~~~~~~ natbib.sty from the documented source natbib.dtx. If
36 natbib.ins has been lost, it may be regenerated by
37 running LaTeX on natbib.dtx. Natbib.ins also extracts
38 the reference sheet source file, natnotes.tex.
39
40 For the bibentry package, TeX or LaTeX bibentry.ins,
41 which extracts bibentry.sty.
42
43 Documentation:- Run LaTeX on natbib.dtx or natbib.ltx. The latter may be
44 ~~~~~~~~~~~~~~~ edited as needed to conform to local requirements (paper
45 size, duplex or not, with or without entire coding).
46 Alternatively, a ltxdoc.cfg file can contain local
47 configurations.
48
49 Similarly for bibentry: LaTeX the bibentry.dtx file.
50
51 Reference Sheet:- Run LaTeX on natnotes.tex (extracted from natbib.dtx when
52 ~~~~~~~~~~~~~~~~~ natbib.ins was processed). This is a 5 page summary of
53 the main natbib features.
54
55
56 The package will accept BibTeX output in the forms:
57 \bibitem{key} (standard numerical format)
58
59 or the following author-year formats:
60 \bibitem[Jones et al.(1990)]{key}... (native natbib style)
61 \bibitem[Jones et al.(1990)Jones, Baker, and Williams]{key}...
62 (extended natbib 5.3 style)
63
64 \bibitem[Jones et al., 1990]{key}... (apalike style)
65 \bibitem[\protect\citeauthoryear{Jones, Baker, and Williams}{Jones
66 et al.}{1990}]{key}... (newapa or chicago styles)
67 \bibitem[\protect\citeauthoryear{Jones et al.}{1990}]{key}... (named style)
68 \bibitem[\protect\astroncite{Jones et al.}{1990}]{key}... (astron style)
69 \bibitem[\protect\citename{Jones et al., }1990]{key}... (authordate style)
70 \harvarditem[Jones et al.]{Jones, Baker, and Williams}{1990}{key}...
71 (harvard style)
72
73 These are all the existing interfaces for author-year format that I could
74 find. Natbib.sty accepts them all, and converts them into its own system.
75
76 Use \citet for in-text form and \citep for parenthetical citations:
77 \citet{key} ==>> Jones et al. (1990) (in-text form)
78 \citep{key} ==>> (Jones et al., 1990) (parenthetical form)
79
80 \citep{key1,key2} ==>> (Jones et al., 1990, 1992)
81 (multiple citations; common authors suppressed)
82 \citep[chap. 2]{key} ==>> (Jones et al., 1990, chap. 2)
83 \citep[see][]{key} ==>> (see Jones et al., 1990)
84 \citep[see][chap. 2]{key} ==>> (see Jones et al., 1990, chap. 2)
85
86 All \cite's may also take a starred version to print the full
87 author list, if that is supported by the bib style file.
88 \citet*{key} ==>> Jones, Baker, and Williams (1990)
89
90 Other citing commands
91 \citeauthor{key} ==>> Jones et al.
92 \citeauthor*{key} ==>> Jones, Baker, and Williams
93 \citeyear{key} ==>> 1990
94 \citeyearpar{key} ==>> (1990)
95
96 With numerical citations,
97 \citep{key} ==>> [23] like standard \cite command
98 \citet{key} ==>> Jones et al. [23]
99
100 For a name like von Braun or della Robbia, coming at the start of a sentence,
101 use \Citet for Von Braun and Della Robbia. Also \Citep, \Citeauthor exist.
102
103 Citation aliasing,
104 \defcitealias{key}{text}
105 \citetalias{key} ==>> text
106 \citepalias{key} ==>> (text)
107 (With the hyperref package, these will be proper links to the reference list)
108
109 Punctuation may be altered with \bibpunct command (see comments and
110 examples in natbib.sty and natbib.dtx)
111
112 Or may be specified with options to the \usepackage{natbib} command.
113
114 Punctuation styles may be set for given .bst file and then invoked by the
115 \bibliographystyle command. This requires making a simple (and legitimate)
116 addition to natbib.sty, or creating a local configuration file natbib.cfg to
117 contain the additions.
118
119 For full details, print out the documentation in natbib.dtx by LaTeXing it.
120
121 -------------------------------------------------------------------------
122 List of changes
123 v8.31b Another compatibility fix: \bibAnnote and \bibAnnoteFile are provided only
124 with merging, so they do not conflict with alternative definitions that are
125 sometimes found in certain BibTeX styles.
126
127 v8.31a Bug fixes by Arthur Ogawa, so that the new eliding and merging features
128 do not cause problems with non-REVTeX classes.
129
130 v8.31 Bug fix: the merging features of v8.3 are supposed to be turned off by default
131 but this was not completely right. With this bug fix, the behaviour without merging
132 is compatible the earlier versions (<= 8.1).
133
134 v8.3 Incorporate the new features from Arthur Ogawa (non-released 8.2) so that they
135 do not conflict with regular natbib usage.
136 Improve compatibility with babel, in particular so that it works right with
137 active characters in the citation keys
138 Fix bug with multiple superscripted citations, to get spacings, comma right
139 Correct problem with chapterbib package
140 Adjust location of optional notes so they are always inside the parentheses
141 (as stated in the documentation)
142
143 v8.2 (by Arthur Ogawa)
144 (This version was never publically released; these features first appear in V8.3)
145
146 Introduce package option [merge], providing the functionality of Thorsten Ohl's
147 mcite package. See the user documentation for details.
148
149 If an @Article reference is merged back with another, there exists the possibility
150 of eliding (typical in APS and AIP journals): if the author matches, then it is
151 elided, if the author matches and the journal does, too, then both are elided.
152 If the author does not match, but the journal matches, the latter is replaced
153 by \textit{ibid.}. It is possible to modify these eliding rules, customizing natbib
154 to your requirements.
155
156 It is possible to change the merge, sort, and compress options even after the
157 package loads, and even after \begin{document}.
158
159 When sorting citations, the sort is now stable.
160
161 It is now possible to automatically add punctuation between citations, like the word `and'.
162
163 Robustness has been improved when first adopting the natbib package and when
164 terminating its use (removing the \usepackage{natbib} statement).
165
166 Compatability with other packages has been improved, particularly any that
167 want to know if \chapter has been defined.
168
169 The \citation command is written to the .aux file with its arguments in the
170 same order as in the user's \cite command, that is, before sorting is done.
171 The old way had the effect of resisting the user's efforts to change the order
172 of citations if sorting was in effect.
173
174 The cite key may have a star and two optional arguments preceding it, as in:
175 \cite{*[<pre-text>][<post-text>]key}, where <pre-text> is prepended to the reference,
176 producing something like ``See, e.g., Bumstead, D. (1945)...'', and where <post-text>
177 is appended to the reference, producing something like,
178 ``... p. 42, and references therein.'' The star (*) signifies that merging is to be done.
179
180 Various implementation changes; see the package documentation for details.
181
182 v8.1 Replace some \edef with \protected@edef, requested by users of preview package
183
184 v8.0 Add \setcitestyle to simplify changing citation punctuation; is to replace
185 \bibpunct, which is retained for compatibility.
186
187 Citation style commands (\setcitestyle, \citestyle, \bibpunct) are no longer
188 limited to the preamble; in particular they may be issued in different chapters
189 with the chapterbib package; even the author--year or numerical mode can
190 be switched and the bibliography is adjusted accordingly. (This has long
191 been requested by several users.) The docstrip option 'nopreonly' is therefore
192 removed, since it is now always active.
193
194 Support for LaTeX 2.09 is removed; I no longer can test it and it only
195 complicates the source file.
196
197 Package option 'colon' always meant putting a semi-colon between multiple
198 citations. This seems odd to me, but I probably thought 'semicolon' was
199 too long. I now have 'semicolon' to be explicit, but 'colon' is still
200 retained (as semi-colon).
201
202 v7.5 (Never released, it is the preliminary 8.0)
203 Superscript citations: if braces specified, they are also superscripted
204 in both in-text and parenthetical citations. Any optional notes are
205 printed before and after as regular text.
206
207 Add \citenum{key} to print the number, even in author-year mode. And
208 without superscripting and without parentheses. This is so
209 superscripted citations can be referred to in-text as regular numbers.
210
211 In-text numerical citations with notes: the notes are now outside the parentheses
212 as this appears more logical. For parenthetical citations, notes are still
213 inside.
214
215 The indexing of citations now has the default format Author [num] in numerical mode.
216 Previously it was Author [date] in both.
217
218 v7.4a Fix bug in the compression option that occurs with hyperref and dvips.
219
220 v7.4 Fix so nonamebreak option works with numerical citations too.
221
222 v7.3 Go over the manual documentation and update it for 2006 rather than 1993.
223 No changes to code.
224
225 v7.2 Allow numerical cite compression without sorting (option compress)
226 Hyperref package no longer suppresses compression
227 Compatibility with citeref package
228 Superscript citations may have braces, defined in \bibpunct
229
230 v7.1 Add warning when multiple citations with common authors and year
231 are missing distinguishing extra letter.
232
233 Modify plainnat.bst et al to include new fields:
234 doi (Digital Object Identifier)
235 eid (Electronic Identifier)
236 The eid is the article sequence number used in place of page numbers
237 for the print version of electronic journals, such as Phys. Rev.
238
239 v7.0b Fix superscript bug
240
241 v7.0a Fix bug in \citenumfont so it works with \textit as well as \it
242 Fix bug with the index.sty package which caused vertical shifts
243 under certain circumstances.
244
245 v7.0 Fix bug with \bibpunct and all the predefined citation styles
246 that use it; blank was missing after post-note punctuation.
247
248 Add \citenumfont and \bibnumfmt to format the citation numbers and
249 numbers in the reference list, respectively.
250
251 Support for authorless works: replace the author in \bibitem with and
252 code and leave the date blank, as
253 \bibitem[ABC98()]{wxyz98}
254 Then \citet{wxyz98} ==>> ABC98
255 \citep{wxyz98) ==>> (ABC98)
256 ie, not only is the date left off, but the punctuation and (for
257 \citet) the braces as well.
258
259 Most author-year bst files insert the text of the KEY field in place
260 of the author if there is no author or editor. The (revised) natbib
261 bst's do this too, but also leave off the date. Thus the KEY text
262 becomes the replacement for author-year.
263
264 \Citet, \Citep, \Citealp, \Citealt, \Citeauthor capitalize first
265 letter of first author's name in case it begins with von or de and
266 comes at the start of a sentence.
267
268 With amsbook, now uses \chapter* instead of erroneous \section*.
269
270 v6.9a Fix bugs with babel 3.6t (earlier versions of babel will not work
271 well with this natbib version). Order of loading is unimportant.
272
273 Add \bibpreamble to allow user to define a preamble to the list of
274 references.
275
276 Fix bug that occurred when optional notes to \cite's began with a
277 command like \S.
278
279 v6.9 The \makeindex can be issued before \usepackage{natbib}
280
281 Add \defcitealias, \citetalias, \citepalias to define and print
282 some identifying code text for the citation:
283 \defcitealias{key}{TEXT} then \citepalias{key} => (TEXT)
284
285 The character coming between the citation and following note is
286 specified by the optional argument to \bibpunct; this must now
287 include a space if that is wanted. The default is now {, } where it
288 was previously {,}.
289
290 Copyright notices in all files (even .bst's) conform to LaTeX Project
291 Public Licence.
292
293 v6.8c Exclude notes, punctuation, both braces from the hyperref link text.
294
295 Add nonamebreak option to prevent line breaks within author names.
296
297 v6.8b Add chapterbib compatibility for hyperref and backref packages
298 (in arrangement with Sebastian Rahtz)
299
300 With hyperref, links are broken between author name and date, to
301 prevent some possible pdftex problems.
302
303 v6.8a Fix some problems with redefinition of \@biblabel
304
305 v6.8 Allow user to be able to redefine \@biblabel for numerical mode
306
307 Fix bug with hyperref package; previously failed with \citep and
308 multiple citations with repeated authors
309
310 Allow cites within cites, as \citep[cited in \citealp{xx}]{yy}
311 (previously these clashed and final brace was missing)
312
313 \citealp and \citealt suppress parenthese in numerical mode too
314
315 Add \citetext{..} to produce citations manually, with help
316 of \citealp, such as
317 \citetext{see \citealp{AA}, or better \citealp{BB}}
318
319 v6.7 Option `longnamesfirst' causes first citation of any reference to use
320 the full author list.
321
322 In numerical mode, \citet with multiple citations suppresses
323 repeated authors, Jones et al. [21, 22].
324
325 A bug is fixed that caused problems with the showkeys package and
326 its `final' option.
327
328 A clash with babel's active characters is fixed up.
329
330 A reference sheet is available, consisting (mainly) of selected text
331 from the main documentation. Source file is natnotes.tex, extracted
332 from natbib.dtx with option `notes'.
333
334 v6.6 Options `sort' and `sort&compress' order multiple citations in one
335 \citep or \citet command to be in the sequence in which they appear
336 in the list of references; this is normally ordered alphabetically
337 and then by year.
338
339 Fix functionality with showkeys and hyperref packages
340
341 Fix \nocite so that warning messages are not always printed with
342 chapterbib package
343
344 All \cite... commands coded from a basic one so that they all have the
345 same syntax: notes and multiple citations always possible, but may not
346 always be meaningful.
347
348 Add \citeyearpar to print year in parentheses; add \citeauthor* to
349 be equivalent to \citefullauthor.
350
351 Package showkeys must be loaded after natbib (this is not an improvement,
352 but seems unavoidable).
353
354 v6.5 Made compatible with KOMA scripts by adding \bib@heading to the
355 definition of thebibliography environment
356
357 change documentation to stress \citet and \citep instead of old
358 syntax with \cite and \cite[]; now both these commands can also
359 take optional arguments for notes, before and after ref.
360
361 v6.4 Made compatible with the chapterbib package of Donald Arseneau
362 which allows multiple bibliographies in one document
363
364 Contains modified coding from Arseneau's cite package to allow
365 numerical citations to be sorted and compressed
366
367 Made compatible with the hyperref package of Sebastian Rahtz and
368 Yannis Haralambous, for use with HyperTeX
369
370 Multiple superscript citations have no space between them
371
372 v6.3 The package `showkeys' used to have some problems when loaded
373 before natbib; this is now repaired
374
375 The supplied .bst files have a bug fixed so that the extra letters
376 added to the dates function properly; they are now added when the
377 abbreviated author list and date are the same for more than one
378 reference (previously the full author list and date determined this,
379 which is incorrect)
380
381 With numerical citations, the extra letters are superfluous; these can
382 now be suppressed with the supplied .bst files
383
384 v6.2 Adds \citet for textual citations in both author-year and numerical
385 modes.
386
387 Adds \bibsep as a length that goes between lines of the reference list
388 Can be changed with \setlength
389
390 Fixes the superscript style of numerical references so that the
391 numbers are the proper (smaller) size
392
393 Fixes a clash with the classes amsart and amsbook
394
395 v6.1 The LaTeX update of December 1995 contains some changes to internal
396 command which natbib has used. Natbib needs to be altered accordingly.
397 In fact, it has been made far more robust against any such future
398 interal changes, although not 100%.
399
400 There are no changes to the user interface.
401
402 V6.0 New method for parsing the author and year parts, which is now done
403 before writing the information to the auxiliary file. This allows
404 numerical citations to be used even with author-year bst files.
405 (Numerical bst files can NEVER generate author-year citations!)
406 Now provide replacements for standard BibTeX bst files so that
407 they may be used for both numerical and author-year.
408
409 Note: the bib style file provided in previous releases (natbib.bst)
410 is no longer provided, since it only meant to be an example. It is now
411 replaced by plainnat.bst and others.
412
413 Citation styles (punctuation, brackets, etc) can be selected in
414 various ways: an improved priority system has now been introduced.
415 For example, any punctuation selection through an option to
416 \usepackage has priority over any prestored citation style.
417
418 \bibpunct can now take a 7th optional argument (at the start of
419 the list) for the punctuation that comes before a post-note.
420
421 It is possible to have all citations and entries in the list of
422 references automatically entered in an index, either with the standard
423 makeidx package or the contributed index package of David M. Jones.
424
425 V5.5: some fixed bugs
426
427 Many internal names have been changed to recommended style, ie with
428 the prefix \NAT@... For example, \@citebegin and \@citeend are
429 now \NAT@open and \NAT@close (these contain the opening and closing
430 brackets).
431
432 Where possible, \def has been replaced by \(re)newcommand.
433
434 Selection of citation format (numerical, superscript, author-year) is
435 coded better; previously, if numerical were ever selected, it was
436 impossible to switch back to author-year.
437
438 ** As a result: ALL CITATION CUSTOMIZATIONS (\bibpunct, \citestyle) MUST
439 ** BE ISSUED BEFORE \begin{document}!!!!! This differs from the
440 ** situation in earlier versions, but is in fact much more logical.
441
442 Add \citep{key} and \citep*{key} as shorthands for
443 \cite[]{key} and \cite*[]{key}, ie for parenthetical citations
444 (this was requested)
445
446 Add \citealt{key} and \citealt*{key} that function like \cite{key} and
447 \cite*{key}, but without brackets. These are textual citations of
448 the form Jones et al. 1990. (Also a requested feature.)
449
450 The amount of hanging indentation in the list of references can be
451 redefined via the length command \bibhang. Change with e.g.
452 \setlength{\bibhang}{2em} %Default is 1em
453
454 V5.4: a few bugs fixed
455
456 add superscript citation style to \bibpunct, as `s' (in place of
457 `n' for numerical or `a' for author-year; improve superscript coding
458
459 add \citestyle command to be able to invoke a preprogrammed citation
460 style that is different from that given in \bibliographystyle
461
462 for (Jones et al, 1994a; Jones et al, 1994b) print instead
463 (Jones et al, 1994a,b)
464 [up until now, it would have printed (Jones et al, 1994a, 1994b) ]
465
466 V5.3: support the new release of harvard.sty, so that natbib will work with
467 those bib styles that are designed for it (agms,dcu,kluwer) This means
468 adding \harvardand, \harvardurl, and some others
469
470 provide \citefullauthor to list all authors for those bib styles that
471 support this: harvard, chicago
472
473 extend the native format of \bibitem to support full author citations
474 too; add starred form of \cite to print full author list, if present.
475
476 fix up a bug that caused accents in citations (not references) to be
477 ignored.
478
479
480 V5.2: \citeauthor and \citeyear make auxiliary file entries so BibTeX
481 can see them; also, any font changes in the author (like {\it Smith})
482 will be localized (in 5.0, the brackets were removed, so all following
483 text was italicized.)
484
485 Internal definition of \cite made to be like that of LaTeX2e, so that
486 multiple citations may have spaces after commas, as \cite{a, b, c}
487
488 A local configuration file natbib.cfg will be read in (2e only) that
489 may contain local \bibstyle@xxx commands.
490
491 V5.1: pure LaTeX2e, not mixed as v5.0 was. Fixes up problems of font
492 commands in the citation labels (like {\em et al.} that caused
493 terrible problems and had a poor ad hoc solution.
494
495 Changes from previous (4.x) versions:
496 \cite now takes two optional arguments for text before and after citation
497 \citeyear and \citeauthor have been added
498 Under LaTeX2e, punctuation can be selected with options in \usepackage
499
500 -------------------------------------------------------------------------
501 2010 Sep 13
502 Patrick W. Daly
503 Max-Planck-Institut f\"ur Sonnensystemforschung
504 (Max Planck Institute for Solar System Research)
505 D-37191 Katlenburg-Lindau, Germany
506 E-mail: [email protected]