path: root/Master/texmf-dist/doc/latex/natbib/README.v831b

                                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{*[<pre-text>][<post-text>]key}, where <pre-text> is prepended to the reference,
        producing something like ``See, e.g., Bumstead, D. (1945)...'', and where <post-text>
        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