From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/natbib/README.v831b | 506 +++++++++++++++++++++++++++++++ 1 file changed, 506 insertions(+) create mode 100644 macros/latex/contrib/natbib/README.v831b (limited to 'macros/latex/contrib/natbib/README.v831b') diff --git a/macros/latex/contrib/natbib/README.v831b b/macros/latex/contrib/natbib/README.v831b new file mode 100644 index 0000000000..ce9a73af2e --- /dev/null +++ b/macros/latex/contrib/natbib/README.v831b @@ -0,0 +1,506 @@ + NATBIB Package +Current Version: 8.31b from 2010/09/13 + +See list of changes below + +This is the natbib package for handling both author-year and numerical +BibTeX styles. + +Manifest:- The natbib package contains the following files: +~~~~~~~~~~ + natbib.dtx -- Documented source file that may be LaTeXed to get the + detailed description and/or coding documentation. + + May be docstripped with option `package,all' to get the + natbib.sty package file, or processed with natbib.ins. + + natbib.ins -- A docstrip batch job to extract natbib.sty and natnotes.tex + from the source file natbib.dtx. + Simply TeX or LaTeX this file. + + This file is embedded in natbib.dtx. If it is missing, then LaTeXing + natbib.dtx will extract it. + + plainnat.bst -- Replacements for plain.bst, abbrv.bst, unsrt.bst, the + abbrvnat.bst standard BibTeX bib style files. These replacements + unsrtnat.bst permit both numerical and author-year citations + + bibentry.dtx -- Documented source file for the bibentry package, defines + \bibentry{key} command that places the bibliography entry + in the text. Useful for descriptive bibliographies. + + bibentry.ins -- The installation file for bibentry. Just TeX or LaTeX it. + +Generation:- Simply run TeX or LaTeX on natbib.ins, which extracts +~~~~~~~~~~~~ natbib.sty from the documented source natbib.dtx. If + natbib.ins has been lost, it may be regenerated by + running LaTeX on natbib.dtx. Natbib.ins also extracts + the reference sheet source file, natnotes.tex. + + For the bibentry package, TeX or LaTeX bibentry.ins, + which extracts bibentry.sty. + +Documentation:- Run LaTeX on natbib.dtx or natbib.ltx. The latter may be +~~~~~~~~~~~~~~~ edited as needed to conform to local requirements (paper + size, duplex or not, with or without entire coding). + Alternatively, a ltxdoc.cfg file can contain local + configurations. + + Similarly for bibentry: LaTeX the bibentry.dtx file. + +Reference Sheet:- Run LaTeX on natnotes.tex (extracted from natbib.dtx when +~~~~~~~~~~~~~~~~~ natbib.ins was processed). This is a 5 page summary of + the main natbib features. + + +The package will accept BibTeX output in the forms: + \bibitem{key} (standard numerical format) + +or the following author-year formats: + \bibitem[Jones et al.(1990)]{key}... (native natbib style) + \bibitem[Jones et al.(1990)Jones, Baker, and Williams]{key}... + (extended natbib 5.3 style) + + \bibitem[Jones et al., 1990]{key}... (apalike style) + \bibitem[\protect\citeauthoryear{Jones, Baker, and Williams}{Jones + et al.}{1990}]{key}... (newapa or chicago styles) + \bibitem[\protect\citeauthoryear{Jones et al.}{1990}]{key}... (named style) + \bibitem[\protect\astroncite{Jones et al.}{1990}]{key}... (astron style) + \bibitem[\protect\citename{Jones et al., }1990]{key}... (authordate style) + \harvarditem[Jones et al.]{Jones, Baker, and Williams}{1990}{key}... + (harvard style) + +These are all the existing interfaces for author-year format that I could +find. Natbib.sty accepts them all, and converts them into its own system. + +Use \citet for in-text form and \citep for parenthetical citations: + \citet{key} ==>> Jones et al. (1990) (in-text form) + \citep{key} ==>> (Jones et al., 1990) (parenthetical form) + + \citep{key1,key2} ==>> (Jones et al., 1990, 1992) + (multiple citations; common authors suppressed) + \citep[chap. 2]{key} ==>> (Jones et al., 1990, chap. 2) + \citep[see][]{key} ==>> (see Jones et al., 1990) + \citep[see][chap. 2]{key} ==>> (see Jones et al., 1990, chap. 2) + +All \cite's may also take a starred version to print the full +author list, if that is supported by the bib style file. + \citet*{key} ==>> Jones, Baker, and Williams (1990) + +Other citing commands + \citeauthor{key} ==>> Jones et al. + \citeauthor*{key} ==>> Jones, Baker, and Williams + \citeyear{key} ==>> 1990 + \citeyearpar{key} ==>> (1990) + +With numerical citations, + \citep{key} ==>> [23] like standard \cite command + \citet{key} ==>> Jones et al. [23] + +For a name like von Braun or della Robbia, coming at the start of a sentence, +use \Citet for Von Braun and Della Robbia. Also \Citep, \Citeauthor exist. + +Citation aliasing, + \defcitealias{key}{text} + \citetalias{key} ==>> text + \citepalias{key} ==>> (text) +(With the hyperref package, these will be proper links to the reference list) + +Punctuation may be altered with \bibpunct command (see comments and + examples in natbib.sty and natbib.dtx) + +Or may be specified with options to the \usepackage{natbib} command. + +Punctuation styles may be set for given .bst file and then invoked by the +\bibliographystyle command. This requires making a simple (and legitimate) +addition to natbib.sty, or creating a local configuration file natbib.cfg to +contain the additions. + +For full details, print out the documentation in natbib.dtx by LaTeXing it. + +------------------------------------------------------------------------- +List of changes + v8.31b Another compatibility fix: \bibAnnote and \bibAnnoteFile are provided only + with merging, so they do not conflict with alternative definitions that are + sometimes found in certain BibTeX styles. + + v8.31a Bug fixes by Arthur Ogawa, so that the new eliding and merging features + do not cause problems with non-REVTeX classes. + + v8.31 Bug fix: the merging features of v8.3 are supposed to be turned off by default + but this was not completely right. With this bug fix, the behaviour without merging + is compatible the earlier versions (<= 8.1). + + v8.3 Incorporate the new features from Arthur Ogawa (non-released 8.2) so that they + do not conflict with regular natbib usage. + Improve compatibility with babel, in particular so that it works right with + active characters in the citation keys + Fix bug with multiple superscripted citations, to get spacings, comma right + Correct problem with chapterbib package + Adjust location of optional notes so they are always inside the parentheses + (as stated in the documentation) + + v8.2 (by Arthur Ogawa) + (This version was never publically released; these features first appear in V8.3) + + Introduce package option [merge], providing the functionality of Thorsten Ohl's + mcite package. See the user documentation for details. + + If an @Article reference is merged back with another, there exists the possibility + of eliding (typical in APS and AIP journals): if the author matches, then it is + elided, if the author matches and the journal does, too, then both are elided. + If the author does not match, but the journal matches, the latter is replaced + by \textit{ibid.}. It is possible to modify these eliding rules, customizing natbib + to your requirements. + + It is possible to change the merge, sort, and compress options even after the + package loads, and even after \begin{document}. + + When sorting citations, the sort is now stable. + + It is now possible to automatically add punctuation between citations, like the word `and'. + + Robustness has been improved when first adopting the natbib package and when + terminating its use (removing the \usepackage{natbib} statement). + + Compatability with other packages has been improved, particularly any that + want to know if \chapter has been defined. + + The \citation command is written to the .aux file with its arguments in the + same order as in the user's \cite command, that is, before sorting is done. + The old way had the effect of resisting the user's efforts to change the order + of citations if sorting was in effect. + + The cite key may have a star and two optional arguments preceding it, as in: + \cite{*[][]key}, where is prepended to the reference, + producing something like ``See, e.g., Bumstead, D. (1945)...'', and where + is appended to the reference, producing something like, + ``... p. 42, and references therein.'' The star (*) signifies that merging is to be done. + + Various implementation changes; see the package documentation for details. + + v8.1 Replace some \edef with \protected@edef, requested by users of preview package + + v8.0 Add \setcitestyle to simplify changing citation punctuation; is to replace + \bibpunct, which is retained for compatibility. + + Citation style commands (\setcitestyle, \citestyle, \bibpunct) are no longer + limited to the preamble; in particular they may be issued in different chapters + with the chapterbib package; even the author--year or numerical mode can + be switched and the bibliography is adjusted accordingly. (This has long + been requested by several users.) The docstrip option 'nopreonly' is therefore + removed, since it is now always active. + + Support for LaTeX 2.09 is removed; I no longer can test it and it only + complicates the source file. + + Package option 'colon' always meant putting a semi-colon between multiple + citations. This seems odd to me, but I probably thought 'semicolon' was + too long. I now have 'semicolon' to be explicit, but 'colon' is still + retained (as semi-colon). + + v7.5 (Never released, it is the preliminary 8.0) + Superscript citations: if braces specified, they are also superscripted + in both in-text and parenthetical citations. Any optional notes are + printed before and after as regular text. + + Add \citenum{key} to print the number, even in author-year mode. And + without superscripting and without parentheses. This is so + superscripted citations can be referred to in-text as regular numbers. + + In-text numerical citations with notes: the notes are now outside the parentheses + as this appears more logical. For parenthetical citations, notes are still + inside. + + The indexing of citations now has the default format Author [num] in numerical mode. + Previously it was Author [date] in both. + + v7.4a Fix bug in the compression option that occurs with hyperref and dvips. + + v7.4 Fix so nonamebreak option works with numerical citations too. + + v7.3 Go over the manual documentation and update it for 2006 rather than 1993. + No changes to code. + + v7.2 Allow numerical cite compression without sorting (option compress) + Hyperref package no longer suppresses compression + Compatibility with citeref package + Superscript citations may have braces, defined in \bibpunct + + v7.1 Add warning when multiple citations with common authors and year + are missing distinguishing extra letter. + + Modify plainnat.bst et al to include new fields: + doi (Digital Object Identifier) + eid (Electronic Identifier) + The eid is the article sequence number used in place of page numbers + for the print version of electronic journals, such as Phys. Rev. + + v7.0b Fix superscript bug + + v7.0a Fix bug in \citenumfont so it works with \textit as well as \it + Fix bug with the index.sty package which caused vertical shifts + under certain circumstances. + + v7.0 Fix bug with \bibpunct and all the predefined citation styles + that use it; blank was missing after post-note punctuation. + + Add \citenumfont and \bibnumfmt to format the citation numbers and + numbers in the reference list, respectively. + + Support for authorless works: replace the author in \bibitem with and + code and leave the date blank, as + \bibitem[ABC98()]{wxyz98} + Then \citet{wxyz98} ==>> ABC98 + \citep{wxyz98) ==>> (ABC98) + ie, not only is the date left off, but the punctuation and (for + \citet) the braces as well. + + Most author-year bst files insert the text of the KEY field in place + of the author if there is no author or editor. The (revised) natbib + bst's do this too, but also leave off the date. Thus the KEY text + becomes the replacement for author-year. + + \Citet, \Citep, \Citealp, \Citealt, \Citeauthor capitalize first + letter of first author's name in case it begins with von or de and + comes at the start of a sentence. + + With amsbook, now uses \chapter* instead of erroneous \section*. + + v6.9a Fix bugs with babel 3.6t (earlier versions of babel will not work + well with this natbib version). Order of loading is unimportant. + + Add \bibpreamble to allow user to define a preamble to the list of + references. + + Fix bug that occurred when optional notes to \cite's began with a + command like \S. + + v6.9 The \makeindex can be issued before \usepackage{natbib} + + Add \defcitealias, \citetalias, \citepalias to define and print + some identifying code text for the citation: + \defcitealias{key}{TEXT} then \citepalias{key} => (TEXT) + + The character coming between the citation and following note is + specified by the optional argument to \bibpunct; this must now + include a space if that is wanted. The default is now {, } where it + was previously {,}. + + Copyright notices in all files (even .bst's) conform to LaTeX Project + Public Licence. + + v6.8c Exclude notes, punctuation, both braces from the hyperref link text. + + Add nonamebreak option to prevent line breaks within author names. + + v6.8b Add chapterbib compatibility for hyperref and backref packages + (in arrangement with Sebastian Rahtz) + + With hyperref, links are broken between author name and date, to + prevent some possible pdftex problems. + + v6.8a Fix some problems with redefinition of \@biblabel + + v6.8 Allow user to be able to redefine \@biblabel for numerical mode + + Fix bug with hyperref package; previously failed with \citep and + multiple citations with repeated authors + + Allow cites within cites, as \citep[cited in \citealp{xx}]{yy} + (previously these clashed and final brace was missing) + + \citealp and \citealt suppress parenthese in numerical mode too + + Add \citetext{..} to produce citations manually, with help + of \citealp, such as + \citetext{see \citealp{AA}, or better \citealp{BB}} + + v6.7 Option `longnamesfirst' causes first citation of any reference to use + the full author list. + + In numerical mode, \citet with multiple citations suppresses + repeated authors, Jones et al. [21, 22]. + + A bug is fixed that caused problems with the showkeys package and + its `final' option. + + A clash with babel's active characters is fixed up. + + A reference sheet is available, consisting (mainly) of selected text + from the main documentation. Source file is natnotes.tex, extracted + from natbib.dtx with option `notes'. + + v6.6 Options `sort' and `sort&compress' order multiple citations in one + \citep or \citet command to be in the sequence in which they appear + in the list of references; this is normally ordered alphabetically + and then by year. + + Fix functionality with showkeys and hyperref packages + + Fix \nocite so that warning messages are not always printed with + chapterbib package + + All \cite... commands coded from a basic one so that they all have the + same syntax: notes and multiple citations always possible, but may not + always be meaningful. + + Add \citeyearpar to print year in parentheses; add \citeauthor* to + be equivalent to \citefullauthor. + + Package showkeys must be loaded after natbib (this is not an improvement, + but seems unavoidable). + + v6.5 Made compatible with KOMA scripts by adding \bib@heading to the + definition of thebibliography environment + + change documentation to stress \citet and \citep instead of old + syntax with \cite and \cite[]; now both these commands can also + take optional arguments for notes, before and after ref. + + v6.4 Made compatible with the chapterbib package of Donald Arseneau + which allows multiple bibliographies in one document + + Contains modified coding from Arseneau's cite package to allow + numerical citations to be sorted and compressed + + Made compatible with the hyperref package of Sebastian Rahtz and + Yannis Haralambous, for use with HyperTeX + + Multiple superscript citations have no space between them + + v6.3 The package `showkeys' used to have some problems when loaded + before natbib; this is now repaired + + The supplied .bst files have a bug fixed so that the extra letters + added to the dates function properly; they are now added when the + abbreviated author list and date are the same for more than one + reference (previously the full author list and date determined this, + which is incorrect) + + With numerical citations, the extra letters are superfluous; these can + now be suppressed with the supplied .bst files + + v6.2 Adds \citet for textual citations in both author-year and numerical + modes. + + Adds \bibsep as a length that goes between lines of the reference list + Can be changed with \setlength + + Fixes the superscript style of numerical references so that the + numbers are the proper (smaller) size + + Fixes a clash with the classes amsart and amsbook + + v6.1 The LaTeX update of December 1995 contains some changes to internal + command which natbib has used. Natbib needs to be altered accordingly. + In fact, it has been made far more robust against any such future + interal changes, although not 100%. + + There are no changes to the user interface. + + V6.0 New method for parsing the author and year parts, which is now done + before writing the information to the auxiliary file. This allows + numerical citations to be used even with author-year bst files. + (Numerical bst files can NEVER generate author-year citations!) + Now provide replacements for standard BibTeX bst files so that + they may be used for both numerical and author-year. + + Note: the bib style file provided in previous releases (natbib.bst) + is no longer provided, since it only meant to be an example. It is now + replaced by plainnat.bst and others. + + Citation styles (punctuation, brackets, etc) can be selected in + various ways: an improved priority system has now been introduced. + For example, any punctuation selection through an option to + \usepackage has priority over any prestored citation style. + + \bibpunct can now take a 7th optional argument (at the start of + the list) for the punctuation that comes before a post-note. + + It is possible to have all citations and entries in the list of + references automatically entered in an index, either with the standard + makeidx package or the contributed index package of David M. Jones. + + V5.5: some fixed bugs + + Many internal names have been changed to recommended style, ie with + the prefix \NAT@... For example, \@citebegin and \@citeend are + now \NAT@open and \NAT@close (these contain the opening and closing + brackets). + + Where possible, \def has been replaced by \(re)newcommand. + + Selection of citation format (numerical, superscript, author-year) is + coded better; previously, if numerical were ever selected, it was + impossible to switch back to author-year. + +** As a result: ALL CITATION CUSTOMIZATIONS (\bibpunct, \citestyle) MUST +** BE ISSUED BEFORE \begin{document}!!!!! This differs from the +** situation in earlier versions, but is in fact much more logical. + + Add \citep{key} and \citep*{key} as shorthands for + \cite[]{key} and \cite*[]{key}, ie for parenthetical citations + (this was requested) + + Add \citealt{key} and \citealt*{key} that function like \cite{key} and + \cite*{key}, but without brackets. These are textual citations of + the form Jones et al. 1990. (Also a requested feature.) + + The amount of hanging indentation in the list of references can be + redefined via the length command \bibhang. Change with e.g. + \setlength{\bibhang}{2em} %Default is 1em + + V5.4: a few bugs fixed + + add superscript citation style to \bibpunct, as `s' (in place of + `n' for numerical or `a' for author-year; improve superscript coding + + add \citestyle command to be able to invoke a preprogrammed citation + style that is different from that given in \bibliographystyle + + for (Jones et al, 1994a; Jones et al, 1994b) print instead + (Jones et al, 1994a,b) + [up until now, it would have printed (Jones et al, 1994a, 1994b) ] + + V5.3: support the new release of harvard.sty, so that natbib will work with + those bib styles that are designed for it (agms,dcu,kluwer) This means + adding \harvardand, \harvardurl, and some others + + provide \citefullauthor to list all authors for those bib styles that + support this: harvard, chicago + + extend the native format of \bibitem to support full author citations + too; add starred form of \cite to print full author list, if present. + + fix up a bug that caused accents in citations (not references) to be + ignored. + + + V5.2: \citeauthor and \citeyear make auxiliary file entries so BibTeX + can see them; also, any font changes in the author (like {\it Smith}) + will be localized (in 5.0, the brackets were removed, so all following + text was italicized.) + + Internal definition of \cite made to be like that of LaTeX2e, so that + multiple citations may have spaces after commas, as \cite{a, b, c} + + A local configuration file natbib.cfg will be read in (2e only) that + may contain local \bibstyle@xxx commands. + + V5.1: pure LaTeX2e, not mixed as v5.0 was. Fixes up problems of font + commands in the citation labels (like {\em et al.} that caused + terrible problems and had a poor ad hoc solution. + +Changes from previous (4.x) versions: + \cite now takes two optional arguments for text before and after citation + \citeyear and \citeauthor have been added + Under LaTeX2e, punctuation can be selected with options in \usepackage + +------------------------------------------------------------------------- +2010 Sep 13 +Patrick W. Daly +Max-Planck-Institut f\"ur Sonnensystemforschung +(Max Planck Institute for Solar System Research) +D-37191 Katlenburg-Lindau, Germany +E-mail: daly@mps.mpg.de -- cgit v1.2.3