natbib 83 (2feb09)

git-svn-id: svn://tug.org/texlive/trunk@12056 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 173 insertions, 26 deletions

diff --git a/Master/texmf-dist/doc/latex/natbib/README.v81 b/Master/texmf-dist/doc/latex/natbib/README.v83
index f1269741554..22b2ef9b2b4 100644
--- a/Master/texmf-dist/doc/latex/natbib/README.v81
+++ b/Master/texmf-dist/doc/latex/natbib/README.v83
@@ -1,10 +1,13 @@
                                 NATBIB Package
-Current Version: 8.1 from 2007/10/30
+Current Version: 8.3 from 2008/12/08
 
 See list of changes below
 
 This is the natbib package for handling both author-year and numerical
-BibTeX styles. It contains the following files:
+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; needs
                   ltxdoc class distributed with LaTeX2e.
@@ -29,20 +32,19 @@ BibTeX styles. It contains the following files:
 
   bibentry.ins -- The installation file for bibentry. Just TeX or LaTeX it.
 
-Installation:-    Simply run TeX or LaTeX on natbib.ins, which extracts
-~~~~~~~~~~~~~~    natbib.sty from the documented source natbib.dtx. You
-                  may first edit natbib.ins if you want natbib209.sty and/or
-                  natbib.drv, the configurable documentation driver. If 
-                  natbib.ins has been lost, it may be regenerated by running
-                  LaTeX on natbib.dtx.
-                  
+Generation:-      Simply run TeX or LaTeX on natbib.ins, which extracts
+~~~~~~~~~~~~      natbib.sty from the documented source natbib.dtx. You
+                  may first edit natbib.ins if you want natbib.drv, the
+                  configurable documentation driver. 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.drv. The latter may be
+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
@@ -53,6 +55,7 @@ Documentation:-   Run LaTeX on natbib.dtx or natbib.drv. The latter may be
 Reference Sheet:- Run LaTeX on natnotes.tex (extracted from natbib.dtx when
 ~~~~~~~~~~~~~~~~~ natbib.dtx 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)
@@ -121,6 +124,54 @@ For full details, print out the documentation in natbib.dtx by LaTeXing it.
 
 -------------------------------------------------------------------------
 List of changes
+  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 
@@ -440,7 +491,7 @@ Changes from previous (4.x) versions:
   Under LaTeX2e, punctuation can be selected with options in \usepackage
 
 -------------------------------------------------------------------------
-2006 Jan 12
+2009 Jan 31
 Patrick W. Daly
 Max-Planck-Institut f\"ur Sonnensystemforschung
 D-37191 Katlenburg-Lindau, Germany
diff --git a/Master/texmf-dist/doc/latex/natbib/natbib.ltx b/Master/texmf-dist/doc/latex/natbib/natbib.ltx
new file mode 100644
index 00000000000..8e29bbeae66
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/natbib/natbib.ltx
@@ -0,0 +1,53 @@
+%%
+%% This is file `natbib.ltx',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% natbib.dtx  (with options: `driver')
+%% ============================================
+%% This is the driver file to produce the LaTeX documentation
+%% from the original source file natbib.dtx.
+%% 
+%% Make changes to it as needed. (Never change the file natbib.dtx!)
+%% ============================================
+%% Copyright 1993-2009 Patrick W Daly
+%% Max-Planck-Institut f\"ur Sonnensystemforschung
+%% Max-Planck-Str. 2
+%% D-37191 Katlenburg-Lindau
+%% Germany
+%% E-mail: daly@mps.mpg.de
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesFile{natbib.ltx}
+        [2009/02/02 8.3 (PWD, AO)]
+\documentclass{ltxdoc}
+%\documentclass[twoside]{ltxdoc}
+%\documentclass[a4paper]{ltxdoc}
+%\documentclass[twoside,a4paper]{ltxdoc}
+\raggedbottom
+
+ %** To include the detailed explanation of the coding, comment out
+ %**   the next line
+\OnlyDescription
+
+ %** To produce a command index: add the following line for one run,
+ %**   then run  makeindex -s gind.ist natbib
+ %**   and reprocess, with or without this line (much faster without)
+% \EnableCrossrefs\CodelineIndex
+
+ %** To produce a change history: add the following line for one run,
+ %**   then run  makeindex -s gglo.ist -o natbib.gls natbib.glo
+ %**   and reprocess, with or without this line (faster without)
+% \RecordChanges
+
+\DisableCrossrefs %May stay; zapped by \EnableCrossrefs
+\CodelineNumbered %May stay
+
+\begin{document}
+   \DocInput{natbib.dtx}
+\end{document}
+
+%% 
+%% End of documentation driver file.
+%%
+%% End of file `natbib.ltx'.
diff --git a/Master/texmf-dist/doc/latex/natbib/natbib.pdf b/Master/texmf-dist/doc/latex/natbib/natbib.pdf
index 55d8b5fbe8c..6a9a4d1a353 100644
--- a/Master/texmf-dist/doc/latex/natbib/natbib.pdf
+++ b/Master/texmf-dist/doc/latex/natbib/natbib.pdf
diff --git a/Master/texmf-dist/doc/latex/natbib/natnotes.pdf b/Master/texmf-dist/doc/latex/natbib/natnotes.pdf
index 19da8e7caf3..c9bb7426821 100644
--- a/Master/texmf-dist/doc/latex/natbib/natnotes.pdf
+++ b/Master/texmf-dist/doc/latex/natbib/natnotes.pdf
diff --git a/Master/texmf-dist/doc/latex/natbib/natnotes.tex b/Master/texmf-dist/doc/latex/natbib/natnotes.tex
index 4d5ccedb3cb..4a3a6addd02 100644
--- a/Master/texmf-dist/doc/latex/natbib/natnotes.tex
+++ b/Master/texmf-dist/doc/latex/natbib/natnotes.tex
@@ -1,5 +1,5 @@
 %%
-%% This is file `natnotes',
+%% This is file `natnotes.tex',
 %% generated with the docstrip utility.
 %%
 %% The original source files were:
@@ -21,7 +21,7 @@
 %% 
 %% For more details, LaTeX the source natbib.dtx.
 %% ==============================================
-%% Copyright 1993-2007 Patrick W Daly
+%% Copyright 1993-2009 Patrick W Daly
 %% Max-Planck-Institut f\"ur Sonnensystemforschung
 %% Max-Planck-Str. 2
 %% D-37191 Katlenburg-Lindau
@@ -31,7 +31,7 @@
 \def\DescribesFile#1 [#2 #3 #4]
   {\def\filename{#1}\def\filedate{#2}\def\fileversion{#3}}
 \DescribesFile{natbib}
-        [2007/10/30 8.1 (PWD)]
+        [2009/02/02 8.3 (PWD, AO)]
 \documentclass{article}
 
 \setlength{\parindent}{0pt}
@@ -205,14 +205,26 @@ hyperlinks.
 \head{Selecting citation style and punctuation}
 Use the command |\setcitestyle| with a list of comma-separated
 keywords (without spaces) as argument.
-\begin{quote}
-  Citation mode: |authoryear| or |numbers| or |super|\\
-  Braces: |round| or |square| or |open={|\emph{char}|},close={|\emph{char}|}|\\
-  Between citations: |semicolon| or |comma| or |citesep={|\emph{char}|}|\\
-  Between author and year: |aysep={|\emph{char}|}|\\
-  Between years with common author: |yysep={|\emph{char}|}|\\
+\begin{itemize}
+\item
+  Citation mode: |authoryear| or |numbers| or |super|
+  %^^A \ifNAT@numbers \ifNAT@super
+\item
+  Braces: |round| or |square| or |open={|\emph{char}|},close={|\emph{char}|}|
+  %^^A \NAT@open \NAT@close
+\item
+  Between citations: |semicolon| or |comma| or |citesep={|\emph{char}|}|
+  %^^A \NAT@sep
+\item
+  Between author and year: |aysep={|\emph{char}|}|
+  %^^A \NAT@aysep
+\item
+  Between years with common author: |yysep={|\emph{char}|}|
+  %^^A \NAT@yrsep
+\item
   Text before post-note: |notesep={|\emph{text}|}|
-\end{quote}
+  %^^A \NAT@cmt
+\end{itemize}
 Defaults are |authoryear|, |round|, |comma|, |aysep={;}|, |yysep={,}|,
 |notesep={, }|
 
@@ -233,13 +245,13 @@ into (Jones et al. 1990; and references therein).
 Redefine |\bibsection| to the desired sectioning command for introducing
 the list of references. This is normally |\section*| or |\chapter*|.
 
-Define |\bibpreamble| to be any text that is to be printed after the heading but
+Redefine |\bibpreamble| to be any text that is to be printed after the heading but
 before the actual list of references.
 
-Define |\bibfont| to be a font declaration, e.g.\ |\small| to apply to
+Redefine |\bibfont| to be a font declaration, e.g.\ |\small| to apply to
 the list of references.
 
-Define |\citenumfont| to be a font declaration or command like |\itshape|
+Redefine |\citenumfont| to be a font declaration or command like |\itshape|
 or |\textit|.
 
 Redefine |\bibnumfmt| as a command with an argument to format the numbers in
@@ -292,6 +304,31 @@ options \texttt{sort}, \texttt{compress}, or \texttt{sort\&compress}.
 These also work with author--year citations, making multiple citations appear
 in their order in the reference list.
 
+
+\head{Merged Numerical References}
+Do not use the \texttt{mcite} package with \thestyle; rather use the package option \texttt{merge}.
+
+
+With this option in effect, citation keys within a multiple |\citep| command
+may contain a leading * that causes them to be merged in the bibliography
+together with the previous citation as a single entry with a single reference
+number. For example, |\citep{feynmann,*salam,*epr}| produces a single number,
+and all three references are listed in the bibliography under one entry with
+that number.
+
+The \texttt{elide} option also activates the merging features, but also sees
+to it that common parts of the merged references (e.g., authors) are not
+repeated but are written only once in the single bibliography entry.
+
+The \texttt{mcite} option turns off the merging and eliding features, but
+allows the special syntax (the * and optional inserted texts) to be ignored.
+
+These functions are available only to numerical-mode citations, and only when
+used parenthetically, similar to the restrictions on \texttt{sort} and
+\texttt{compress}.
+
+They also require special \texttt{.bst} files, as provided for example by the
+American Physical Society for their REV\TeX\ class.
 \head{Long author list on first citation}
 Use option \texttt{longnamesfirst} to have first citation automatically give
 the full list of authors.
@@ -333,11 +370,17 @@ is read in after the main package file.
      |\chapter| command; to be used with the \texttt{chapterbib} package;
 \item[\ttfamily nonamebreak] keeps all the authors' names in a citation on
      one line; causes overfull hboxes but helps with some \texttt{hyperref}
-     problems.
+     problems;
+\item[\ttfamily merge] to allow the * prefix to the citation key,
+     and to merge such a citation's reference with that of the previous
+     citation;
+\item[\ttfamily elide] to elide common elements of merged references, like
+     the authors or year;
+\item[\ttfamily mcite] to recognize (and ignore) the merging syntax.
 \end{description}
 \end{document}
 %% 
 %% End of Reference Sheet file
 %% 
 %%
-%% End of file `natnotes'.
+%% End of file `natnotes.tex'.