\title{The \textsf{natbib} package}
\author{Patrick W. Daly\\
Max-Planck-Institut f\"ur Aeronomie\\
Max-Planck-Str. 2\\
D-37191 Katlenburg-Lindau\\
Germany\\
E-mail: \texttt{daly@linmpi.mpg.de}}   

\def\DescribeMacro#1{}

\begin{Article}
\begin{abstract}
  The \textsf{natbib} package is a reimplementation of the \LaTeX\ 
  \verb|\cite| command, to work with both author--year and numerical
  citations. It is compatible with the standard bibliographic style
  files, such as \texttt{plain.bst}, as well as with those for
  \texttt{harvard}, \texttt{apalike}, \texttt{chicago},
  \texttt{astron}, \texttt{authordate}, and of course \textsf{natbib}.
  
  In contrast to the packages listed above, the \textsf{natbib}{} package
  supports not only the various author--year bibliography styles, but
  also those for standard numerical citations. In fact, it can also
  produce numerical citations even with an author--year bibliographic
  style, something that permits easy switching between the two
  citation modes. To this end, replacements for the standard \LaTeX\ 
  \texttt{.bst} files are also provided.
  
  It is possible to define the citation \emph{style} (type of brackets
  and punctuation between citations) and even to associate it with the
  name of the bibliographic style so that it is automatically
  activated. Citation styles can be defined for local \texttt{.bst}
  files by means of a configuration file \texttt{natbib.cfg}.
  
  It is compatible with the packages: \texttt{babel}, \texttt{index},
  \texttt{showkeys}, \texttt{chapterbib}, \texttt{hyperref},
  \texttt{koma} and with the classes \texttt{amsbook} and
  \texttt{amsart}. It can also emulate the sorting and compressing
  functions of the \texttt{cite} package (with which it is otherwise
  incompatible).
  
  The \textsf{natbib} package therefore acts as a single, flexible
  interface for most of the available bibliographic styles.
\end{abstract}  

\section{Introduction}
The first problem of using author--year literature citations with standard
\LaTeX{} is that the two forms of citations are not supported. These are:
\begin{quote}
textual: \dots\ as shown by Jones et al. (1990) \dots\\
parenthetical: \dots as shown (Jones et al., 1990) \dots
\end{quote}
There is only one \verb|\cite| command to do both jobs.

A second problem is that the \texttt{thebibliography} environment for
listing the references insists on including the {\em labels\/} in the
list. These labels are normally the numbers, needed for referencing. In
the author--year system, they are superfluous and should be left off.
Thus, if one were to make up a bibliography with the author--year as
label, as
\begin{quote}
\begin{verbatim}
\begin{thebibliography}{...}
\bibitem[Jones et al., 1990]{jon90}
Jones, P. K., . . .
\end{thebibliography}
\end{verbatim}
\end{quote}
then \verb|\cite{jon90}| produces the parenthetical citation [Jones et al.,
1990], but there is no way to get the textual citation. Furthermore,
the citation text will also be included in the list of references. 

The final problem is to find a \BibTeX{} bibliography style that will be
suitable.

\section{Previous solutions}
Although the author--year citation mode is not supported by
\emph{standard} \LaTeX, there are a number of contributed packages that
try to solve this problem. The various bibliographic styles
(\texttt{.bst} files) that exist are usually tailored to be used with a
particular \LaTeX{} package.

I have found a large number of \texttt{.bst} files on file servers that may
act as indicators of the various systems available.

\subsection{The \texttt{natsci.bst} style}
What gave me my first inspiration was Stephen Gildea's \texttt{natsci.bst}
for use with his \texttt{agujgr.sty} file. This showed me that the problem
was solvable. However, Gildea's style formats \verb|\bibitem| just as I
illustrated above: with an optional label consisting of abbreviated
authors and year. Thus only parenthetical citations can be accommodated.
The list of references, however, is fixed up in his style files.

\subsection{The \texttt{apalike.bst} style}
Oren Patashnik, the originator of \BibTeX{} and the standard \texttt{.bst}
files, has also worked on an author--year style, called \texttt{apalike.bst}
with a corresponding \texttt{apalike.sty} to support it. Again, only the
parenthetical citation is provided. Except for the fact that his style
works with version~0.99 of \BibTeX, its functionality is identical to that
of the \texttt{natsci} files.

Patashnik does not like author--year citations. He makes this very clear
in his \BibTeX{} manuals and in the header to \texttt{apalike.bst}.
Nevertheless, one should respect his work in this area, simply because he
should be the best expert on matters of \BibTeX. Thus \texttt{apalike.bst}
could be the basis for other styles.

The form of the \texttt{thebibliography} entries in this system is
\begin{verbatim}
\bibitem[Jones et al., 1990]{jon90}...
\end{verbatim}
as illustrated earlier. This is the most minimal form that
can be given. I name it the \texttt{apalike} variant, after
Patashnik's \texttt{apalike.bst} and \texttt{apalike.sty}. However,
there could be many independent \texttt{.bst} files that follow this
line.

The bibliography style files belonging to this group include:
\texttt{apalike}, \texttt{apalike2}, \texttt{cea}, \texttt{cell}, 
\texttt{jmb}, \texttt{phapalik}, \texttt{phppcf}, and \texttt{phrmp}.


\subsection{The \texttt{newapa} style}
A major improvement was achieved with \texttt{newapa.bst} and the
accompanying \texttt{newapa.sty} files by Stephen N. Spencer and Young U.
Ryu. Under their system, three separate items of information are included
in the \verb|\bibitem| label, to be used as required. These are: the full
author list, the abbreviated list, and the year. This is accomplished by
means of a \verb|\citeauthoryear| command included in the label, as
\begin{verbatim}
\bibitem[\protect\citeauthoryear{Jones, Barker,
  and Williams}{Jones et al.}{1990}]{jon90}...
\end{verbatim}
Actually, this only illustrates the basic structure of
\verb|\citeauthoryear|; the \texttt{newapa} files go even further to
replace some words and punctuation with commands. For example, the
word `and' above is really \verb|\betweenauthors|, something that must
be defined in the \texttt{.sty} file.  Of course,
\verb|\citeauthoryear| is also defined in that file. A number of
different \verb|\cite| commands are available to print out the
citation with complete author list, with the short list, with or
without the date, the textual or parenthetical form.

Thus the \verb|\citeauthoryear| entry in \verb|\bibitem| is very flexible,
permitting the style file to generate every citation form that one might
want. It is used by a number of other styles, with corresponding
\texttt{.sty} files. They all appear to have been inspired by 
\texttt{newapa.bst}, although they lack the extra punctuation commands. 

Bibliographic style files belonging to the \texttt{newapa} group
include \texttt{newapa}, \texttt{chicago}, \texttt{chicagoa},
\texttt{jas99}, and \texttt{named}.
The last of these, \texttt{named.bst}, uses \verb|\citeauthoryear| in a
slightly different manner, with only two arguments: the short list and
year.

\subsection{The Harvard family}
The same effect is achieved by a different approach in the Harvard family
of bibliographic styles. Here a substitute for \verb|\bibitem| is used, as
\begin{verbatim}
\harvarditem[Jones et al.]{Jones, Baker, and
   Williams}{1990}{jon90}...
\end{verbatim}
The accompanying interface package file is called \texttt{harvard.sty}
and is written by Peter Williams and Thorsten Schnier. It defines
\verb|\harvarditem| as well as the citation commands \verb|\cite|, for
parenthentical, and \verb|\citeasnoun|, for textual citations. The
first citation uses the long author list, following ones the shorter
list, if it has been given in the optional argument to
\verb|\harvarditem|.

Bibliography styles belonging to the Harvard family are \texttt{agsm},
\texttt{dcu}, \texttt{kluwer}.

This package has been updated for \LaTeXe, with many additions to
add flexibility. The result is a powerful interface that should meet most
citation needs. (It does not suppress repeated authors, though,
as \textsf{natbib}{} does.)

\subsection{The \texttt{astronomy} style}
Apparently realizing the limitations of his \texttt{apalike} system, Oren
Patashnik went on to develop a `true' \texttt{apa} bibliographic style,
making use of the method already employed by an astronomy journal. This
is actually very similar to the \texttt{newapa} label but with only the
short list of authors:
\begin{verbatim}
\bibitem[\protect\astroncite
   {Jones et al.}{1990}]{jon90}  ...
\end{verbatim}
It requires the package file \texttt{astron.sty} 
or any other style that defines \verb|\astroncite| appropriately.

Bibliographic styles belonging to the astronomy group are
\texttt{apa}, \texttt{astron}, \texttt{bbs}, \texttt{cbe}, 
\texttt{humanbio}, \texttt{humannat}, and \texttt{jtb}.

This is as good as the \verb|\citeauthoryear| command, although not as
flexible since the full list of authors is missing.

\subsection{The \texttt{authordate} style}
Finally, I have also found some packages making use of a label command
called \verb|\citename| in the form
\begin{verbatim}
\bibitem[\protect\citename
 {Jones et al., }1990]{jon90}  ...
\end{verbatim}

This is not a good system since the author list and date are not cleanly
separated as individual arguments, and since the punctuation is included
in the label text. It is better to keep the punctuation fully removed, as
part of the definitions in the \texttt{.sty} file, for complete flexibility.

Bibliographic styles belonging to this group are
\texttt{authordate1}, \texttt{authordate2}, \texttt{authordate3}, 
\texttt{authordate4}, and \texttt{aaai-named},
with an accompanying style file \texttt{authordate1-4.sty}.

\section{The \textsf{natbib}{} system}
The form of the \verb|\bibitem| entry that I have used for all my
bibliographic styles is only slightly more complicated than the minimal
one, but allows a clean separation between authors and date:
\begin{verbatim}
\bibitem[Jones et al.(1990)]{jon90}...
\end{verbatim}
\noindent or alternatively
\begin{verbatim}
\bibitem[Jones et al.(1990)Jones, Baker,
   and Williams]{jon90}...
\end{verbatim}
\noindent One weakness of the \textsf{natbib}{} format is that it fails
if the author list itself contains parentheses! This may be fixed
by grouping  the author list in curly braces.

I wanted to name the system something like `natural sciences bibliography',
intending it to be a variant of \texttt{natsci.sty}. Since that name
was already taken, I resorted to the rather cryptic, and definitely ugly,
\textsf{natbib}.

The \texttt{natbib.sty} package\footnote{Formerly called a \emph{style 
file} in the older \LaTeX~2.09 terminology.}
supports not only my own \verb|\bibitem| format, but
also all the others described above, plus numerical citation modes.
The additional questions of citation style (type of brackets, commas or
semi-colons between citations) can be defined once and for each
\texttt{.bst} file and need never be specified explicitly in the source text.
The use of \verb|\cite| is the same for all citation styles, meaning that the
additional features that might be available in the `proper' \texttt{.sty}
file will be missing. (This could be changed later.) The result is a
single \LaTeX{} package to handle {\em all\/} the bibliographic
styles in a uniform manner.

In previous versions of this package, each \texttt{.bst} file was
either numerical or author--year only. Applying the wrong mode led to
grotesque results, and the mode could not always be selected
automatically. With version~6.0 onwards, all the author--year
bibliographic style files can also be used for \emph{numerical}
citations, by simply selecting the mode in one of the ways described
on pp.~\pageref{sec:bibpunct} and \pageref{sec:usage}. It is not possible
to employ author-year citations with pure numerical \texttt{.bst}
files, and never will be.

\section{Using this package}\label{sec:usage}
\textsf{natbib} is loaded in the normal way:
\begin{verbatim}
\documentclass[..]{...}
\usepackage[options]{natbib}
\end{verbatim}
The options available provide a means of specifying the
punctuation for citations:
\begin{description}
\item[\ttfamily round] (default) for round parentheses;
\item[\ttfamily square] for square brackets;
\item[\ttfamily curly] for curly braces;
\item[\ttfamily angle] for angle brackets;
\item[\ttfamily colon] (default) to separate multiple citations with
  colons;
\item[\ttfamily comma] to use commas as separaters;
\item[\ttfamily authoryear] (default) for author--year citations;
\item[\ttfamily numbers] for numerical citations;
\item[\ttfamily super] for superscripted numerical citations, as in
  \emph{Nature};
\item[\ttfamily sort] orders multiple citations into the sequence in
  which they appear in the list of references;
\item[\ttfamily sort\&compress] as \texttt{sort} but in addition
  multiple numerical citations are compressed if possible (as 3--6,
  15);
\item[\ttfamily longnamesfirst] makes the first citation of any
  reference the equivalent of the starred variant (full author list)
  and subsequent citations normal (abbreviated list);
\item[\ttfamily sectionbib] redefines \verb|\thebibliography| to issue
  \verb|\section*| instead of \verb|\chapter*|; valid only for classes
  with a \verb|\chapter| command; to be used with the
  \texttt{chapterbib} package.
\end{description}

If any of the formatting options are selected, the predefined citation
styles in the commands \verb|\bibstyle@|\textit{bst} will be no longer
be effective. If either \verb|\bibpunct| or \verb|\citestyle| is given
in the preamble, the above punctuation options will no longer hold.


\subsubsection{Basic commands}
In this paper, I distinguish between the citation \emph{mode} (author--year
or numerical) and citation \emph{style} (the type of punctuation used for
citations). The citation style is something that is independent of the
bibliography style and is not programmed in the \texttt{.bst} files.

\subsection{Basic citation commands}

\DescribeMacro{citet} \DescribeMacro{citep} The \textsf{natbib} package
has two basic citation commands, \verb|\citet| and \verb|\citep| for
\emph{textual} and \emph{parenthetical} citations, respectively.
There also exist the starred versions \verb|\citet*| and
\verb|\citep*| that print the full author list, and not just the
abbreviated one.  All of these may take one or two optional arguments
to add some text before and after the citation.
\begin{flushleft}
  \verb|\citet{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al. (1990)\\
  \verb|\citet[chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al. (1990, chap.~2)\\[0.5ex]
  \verb|\citep{jon90}| \\
\hspace{2em}$\Rightarrow$ (Jones et al., 1990)\\
  \verb|\citep[chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ (Jones et al., 1990, chap.~2)\\
  \verb|\citep[see][]{jon90}| \\
\hspace{2em}$\Rightarrow$ (see Jones et al., 1990)\\
  \verb|\citep[see][chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ (see Jones et al., 1990, chap.~2)\\[0.5ex]
  \verb|\citet*{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones, Baker, and Williams (1990)\\
  \verb|\citep*{jon90}| \\
\hspace{2em}$\Rightarrow$ (Jones, Baker, and Williams, 1990)
\end{flushleft}
The starred versions can only list the full authors if the \texttt{.bst}
file supports this feature; otherwise, the abbreviated list is printed.

In standard \LaTeX, the \verb|\cite| command can only take a single optional
text for a note after the citation; here, a single optional text is a
post-note, while two are the pre- and post-notes. To have only a pre-note, it
is necessary to provide an empty post-note text, as shown above.

\subsubsection{Multiple citations}
Multiple citations may be made as usual, by including more than one
citation key in the \verb|\cite| command argument. 
\emph{If adjacent citations
have the same author designation but different years, then the author
names are not reprinted.}
\begin{flushleft}
  \verb|\citet{jon90,jam91}| \\
\hspace{2em}$\Rightarrow$ Jones et al. (1990); James et al. (1991)\\
  \verb|\citep{jon90,jam91}| \\
\hspace{2em}$\Rightarrow$ (Jones et al., 1990; James et al. 1991)\\
  \verb|\citep{jon90,jon91}| \\
\hspace{2em}$\Rightarrow$ (Jones et al., 1990, 1991)\\
  \verb|\citep{jon90a,jon90b}| \\
\hspace{2em}$\Rightarrow$ (Jones et al., 1990a,b)
\end{flushleft}

\subsubsection{Numerical mode}
These examples are for author--year citation mode. In numerical mode, the 
results are different.
\begin{flushleft}
  \verb|\citet{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al. [21]\\
  \verb|\citet[chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al. [21, chap.~2]\\[0.5ex]
  \verb|\citep{jon90}| \\
\hspace{2em}$\Rightarrow$ [21]\\
  \verb|\citep[chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ [21, chap.~2]\\
  \verb|\citep[see][]{jon90}| \\
\hspace{2em}$\Rightarrow$ [see 21]\\
  \verb|\citep[see][chap.~2]{jon90}| \\
\hspace{2em}$\Rightarrow$ [see 21, chap.~2]\\[0.5ex]
  \verb|\citep{jon90a,jon90b}| \\
\hspace{2em}$\Rightarrow$ [21, 32]
\end{flushleft}
The authors can only be listed if the \texttt{.bst} file supports
author--year citations. The standard \texttt{.bst} files, such as
\texttt{plain.bst}, are numerical only and transfer no author--year
information to \LaTeX. In this case, \verb|\citet| prints ``\textbf{(author?)} 
[21].''

\DescribeMacro{cite} In the original versions of \textsf{natbib}, the
traditional \verb|\cite| command was used for both textual and
parenthetical citations. The presence of an empty optional text in
square brackets signalled parenthetical. This syntax has been retained
for compatibility, but is no longer encouraged.  This means that
\verb|\cite| (without notes) is the same as \verb|\citet| in
author--year mode, whereas in numerical mode, it is the same as
\verb|\citep|.  The starred version, as well as the one or two
optional notes, may also be used.

It is possible to have multiple citations sorted into the same
sequence as they appear in the list of references, regardless of their
order as arguments to the \verb|\cite| commands. The option
\texttt{sort} is required for this feature. See p.~\pageref{sec:sort}.

Some publishers require that the first citation of any given reference
be given with the full author list, but that all subsequent ones with
the abbreviated list. Include the option \texttt{longnamesfirst} to
enable this for \textsf{natbib}. See p.~\pageref{sec:long}.

\subsection{Extended citation commands}

\DescribeMacro{citealt}
\DescribeMacro{citealp}
As an alternative form of citation, \verb|\citealt| is the same as
\verb|\citet| but \emph{without any parentheses}. Similarly,
\verb|\citealp| is \verb|\citep| with the parentheses turned off.
Multiple references, notes, and the starred variants also exist.
\begin{flushleft}
  \verb|\citealt{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al.\ 1990\\
  \verb|\citealt*{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones, Baker, and Williams 1990\\
  \verb|\citealp{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al., 1990\\
  \verb|\citealp*{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones, Baker, and Williams, 1990\\
  \verb|\citealp{jon90,jam91}| \\
\hspace{2em}$\Rightarrow$ Jones et al., 1990; James et al., 1991\\
  \verb|\citealp[pg.~32]{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al., 1990, pg.~32
\end{flushleft}

\DescribeMacro{citeauthor}
\DescribeMacro{citeyear}
\DescribeMacro{citeyearpar}
\DescribeMacro{citefullauthor}
\subsubsection{Partial citations}
In author--year schemes, it is sometimes desirable to be able to refer to
the authors without the year, or vice versa. This is provided with the
extra commands
\begin{flushleft}
  \verb|\citeauthor{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones et al.\\
  \verb|\citeauthor*{jon90}| \\
\hspace{2em}$\Rightarrow$ Jones, Baker, and Williams\\
  \verb|\citeyear{jon90}|   \\
\hspace{2em}$\Rightarrow$ 1990\\
  \verb|\citeyearpar{jon90}| \\
\hspace{2em}$\Rightarrow$ (1990)
\end{flushleft}
There also exists a command \verb|\citefullauthor| which is equivalent
to \verb|\citeauthor*|.  If the full author information is missing,
then \verb|\citeauthor*| is the same as \verb|\citeauthor|, printing
only the abbreviated list.  This also applies to the starred versions
of \verb|\citet| and \verb|\citep|.  If the author or year information
is missing (as is the case with the standard \LaTeX{} \texttt{.bst}
files), these commands issue a warning.  They may also be used with
numerical citations, provided an author--year \texttt{.bst} file is
being employed.

All \verb|\cite..| commands have the same syntax, allowing multiple
citations and up to two notes (there is, however, no starred
\verb|\citeyear| variant). It does not really make much sense to add
notes to \verb|\citeyear| and \verb|\citeauthor|, especially with
multiple citations; however, this can be done --- there will be no
error message --- but the results are sometimes strange. For example,
in numerical mode, the notes are fully ignored, while in author--year
mode, only the post-note is accepted.  Multiple citations in
\verb|\citet| are also not recommended (nor are they in my opinion
meaningful), but if they are used with notes, the pre-note will appear
before each year, and the post-note only after the last year. These
are admittedly bugs, but the effort to remove them is not justified by
the questionable usefulness of these features.

In summary, notes are only intended for \verb|\citep| but they may
also be used with \verb|\citet| in author--year mode, with single
citations. In any other situation, the results are unpredictable.

\subsection{Selecting citation punctuation}\label{sec:bibpunct}

\DescribeMacro{bibpunct}
The above examples have been printed with the default citation style.
It is possible to change this, as well as to select numerical or
author--year mode, by means of the \verb|\bibpunct| command, which takes 
one optional and six mandatory arguments. 
The six mandatory arguments:
\begin{enumerate}
\item the opening bracket symbol, default = (
\item the closing bracket symbol, default = )
\item the punctuation between multiple citations, default = ;
\item the letter `n' for numerical style, or `s' for numerical
  superscript style, any other letter for author--year, default =
  author--year; note, it is not necessary to specify which
  author--year interface is being used, for all will be recognized;
\item the punctuation that comes between the author names and the year
  (parenthetical case only), default = ,
\item the punctuation that comes between years or numbers when common
  author lists are suppressed (default = ,); if both authors and years
  are common, the citation is printed as `1994a,b', but if a space is
  wanted between the extra letters, then include the space in the
  argument, as \verb|{,~}|.
  
  For numerical mode, \verb|\citet{jon90,jon91}| produces `Jones et
  al.\ [21, 22]' with this punctuation between the numbers.  A space
  is automatically included for numbers, but not for superscripts.

\end{enumerate}

The optional argument is the character preceding a post-note, and
default is a comma.  The \verb|\bibpunct| command must be issued in
the preamble, that is, before \verb|\begin{document}|.

Example~1, \verb|\bibpunct{[}{]}{,}{a}{}{;}| changes the output of
\begin{verbatim}
 \citep{jon90,jon91,jam92}
\end{verbatim}
\noindent into [Jones et al. 1990; 1991, James et al. 1992].

Example~2, \verb|\bibpunct[;]{(}{)}{,}{a}{}{;}| changes the output of
\begin{verbatim}
  \citep[and references therein]{jon90}
\end{verbatim}
\noindent into (Jones et al. 1990; and references therein).


\DescribeMacro{bibstyle@xxx} Usually the citation style is determined
by the journal for which one is writing, and is as much a part of the
bibliography style as everything else. The \textsf{natbib}{} package
allows punctuation definitions to be directly coupled to the
\verb|\bibliographystyle| command that must always be present when
\BibTeX{} is used. It is this command that selects the \texttt{.bst}
file; by adding such a coupling to \textsf{natbib}{} for every
\texttt{.bst} file that one might want to use, it is not necessary to
add \verb|\bibpunct| explicitly in the document itself, unless of
course one wishes to override the preset values.

Such a coupling is achieved by defining a command
\verb|\bibstyle@|{\em bst}, where {\em bst\/} stands for the name of
the \texttt{.bst} file. For example, the American Geophysical Union
(AGU) demands in its publications that citations be made with square
brackets and separated by semi-colons. I have an \texttt{agu.bst} file
to accomplish most of the formatting, but such punctuations are not
included in it. Instead, \textsf{natbib}{} has the definition
\begin{verbatim}
\newcommand{\bibstyle@agu}
 {\bibpunct{[}{]}{;}{a}{,}{,~}}
\end{verbatim}

These style defining commands may contain more than just \verb|\bibpunct|.
Some numerical citation scheme require even more changes. For example,
the journal \emph{Nature} not only uses superscripted numbers for 
citations, it also prints the numbers in the list of references without
the normal square brackets. To
accommodate this, \textsf{natbib}{} contains the style definition
\begin{verbatim}
\newcommand{\bibstyle@nature}
 {\bibpunct{}{}{,}{s}{}{\textsuperscript{,}}%
     \gdef\NAT@biblabelnum##1{##1.}}
\end{verbatim}
The redefined \verb|\NAT@biblabelnum| command specifies how the
reference numbers are to be formatted in the list of references
itself.  The redefinition must be made with \verb|\gdef|, not
\verb|\def| or \verb|\renewcommand|.

The selected punctuation style and other redefinitions will not be in
effect on the first \LaTeX{} run, for they are stored to the auxiliary
file for the subsequent run.

The user may add more such definitions of his own, to accommodate those
journals and \texttt{.bst} files that he has. He may either add them to
his local copy of \texttt{natbib.sty}, or better put them into a file
named \texttt{natbib.cfg}. This file will be read in if it exists,
adding any local configurations. Thus such configurations can survive
future updates of the package. (This is for \LaTeXe{} only.)

Any explicit call to \verb|\bibpunct| has priority over the 
predefined citation styles.

\DescribeMacro{citestyle} A preprogrammed citation style is normally
invoked by the command \verb|\bibliographystyle|, as described above.
However, it may be that one wants to apply a certain citation style to
another bibliography style. This may be done with \verb|\citestyle|,
given \emph{before} \verb|\begin{document}|. For example, to use the
  \texttt{plainnat} bibliography style (for the list of references)
  with the \emph{Nature} style of citations (superscripts),
\begin{verbatim}
\documentclass{article}
\usepackage{natbib}
. . . . .
\citestyle{nature}
\begin{document}
\bibliographystyle{plainnat}
. . . . .
\end{verbatim}
All changes to the citation
style, including punctuation, must be made before \verb|\begin{document}|,
which freezes the citation style.

\subsection{Priority of style commands}\label{sec:priority}
The citation style (punctuation and mode) can be selected by means of
the \verb|\bibpunct|, \verb|\citestyle|, and predefined
\verb|\bibstyle@|\textit{bst} commands. They can also be selected by
\LaTeXe{} options (p.~\pageref{sec:usage}). What happens if there are
several conflicting selections?

The lowest priority is assigned to the predefined
\verb|\bibstyle@|\textit{bst} commands, since they are implicit and
not obvious to the user. The \LaTeXe{} options have the next priority.
Finally, any selection by \verb|\bibpunct| and/or \verb|\citestyle|
overrides those of the other methods.

\subsection{Other formatting options}

\DescribeMacro{bibsection} The list of references normally appears as
a \verb|\section*| or \verb|\chapter*|, depending on the main class.
If one wants to redesign one's own heading, say as a numbered section
with \verb|\section|, then \verb|\bibsection| may be redefined by the
user accordingly.

Redefine \verb|\bibsection| to the desired sectioning command for
introducing the list of references. This is normally \verb|\section*|
or \verb|\chapter*|.


\DescribeMacro{bibfont} The list of references is normally printed in
the same font size and style as the main body. However, it is possible
to define \verb|\bibfont| to be font commands that are in effect
within the \texttt{thebibliography} environment.

Redefine \verb|\bibfont| to be a font declaration, e.g.\ \verb|\small|
to apply to the list of references.


\DescribeMacro{bibhang} The list of references for author--year
styles uses a hanging indentation format: the first line of each
reference is flush left, the following lines are set with an
indentation from the left margin. This indentation is 1~em by default
but may be changed by redefining (with \verb|\setlength|) the length
parameter \verb|\bibhang|.

The indentation after the first line of each reference is given by 
\verb|\bibhang|; change this with the \verb|\setlength| command.

\DescribeMacro{bibsep} The vertical spacing between references in the
list, whether author--year or numerical, is controlled by the length
\verb|\bibsep|. If this is set to 0~pt, there is no extra line spacing
between references. The default spacing depends on the font size
selected in \verb|\documentclass|, and is almost a full blank line.
Change this by redefining \verb|\bibsep| with \verb|\setlength|
command.

The vertical spacing between references is set by \verb|\bibsep|;
change this with the \verb|\setlength| command.


\subsection{Automatic Indexing of Citations}

\DescribeMacro{citeindextrue} \DescribeMacro{citeindexfalse} If one
wishes to have the citations entered in the \texttt{.idx} indexing
file, it is only necessary to issue \verb|\citeindextrue| at any point
in the document. All following \verb|\cite| commands, of all
variations, then insert the corresponding entry to that file. With
\verb|\citeindexfalse|, these entries will no longer be made.

The \verb|\bibitem| commands in the \texttt{thebibliography}
environment will also make index entries. If this is not desired, then
issue \verb|\citeindexfalse| before \verb|\bibliography| or
\verb|\begin{thebibliography}|.  Of course, \verb|\makeindex| must
  also be issued in the preamble to activate indexing, as usual.
  Otherwise, no indexing is done at all.  Make sure that the document
  has been processed at least twice after the last \BibTeX\ run before
  running the \texttt{makeindex} program.
  
  \DescribeMacro{NAT@idxtxt} The form of the index entries is set by
  the internal \verb|\NAT@idxtxt|, which can be redefined by hackers
  if wanted (in the \texttt{natbib.cfg} file please). By default, it
  prints the short author list plus date in the current parenthesis
  style.
  
  The \textsf{natbib} package can also be used with the \texttt{index}
  package of David~M. Jones. The order in which the packages are
  loaded is not important.
  
  \DescribeMacro{citeindextype} In that package, multiple index lists
  may be made by means of a \verb|\newindex| command. For example, it
  may be desirable to put all the citation indexing into a separate
  list. First that list must be initiated with, e.g.,
\begin{verbatim}
  \newindex{cite}{ctx}{cnd}{List of Citations}
\end{verbatim}
and then the automatic citation indexing associated with this list with the
\textsf{natbib} command
\begin{verbatim}
 \renewcommand{\citeindextype}{cite}
\end{verbatim}
See the documentation for \texttt{index.sty} for details.

\subsection{Hyper\TeX\ compatibility}
\textsf{natbib} is compatible with the \texttt{hyperref} 
package of Sebastian Rahtz and Yannis Haralambous, for use with
Hyper\TeX. The compatibility is of a mutual nature: both packages contain
coding that interact with that of the other. 

\subsection{Multiple bibliographies in one document}\label{sec:chapbib}

\textsf{natbib} is compatible with the
\texttt{chapterbib} package of Donald Arseneau and Niel Kempson, which
makes it possible to have several bibliographies in one document. The
usual application is to have bibliographies in each chapter of a book,
especially if they have been written by different authors.

The \texttt{chapterbib} package works in a very natural way for the
author; only the editor who puts all the chapters together into one book
has to do some extra work. 

The package makes use of the \verb|\include| command, and it is in fact every
\verb|\include|d file that has its own bibliography. For large books, it makes
very good sense to take advantage of this feature in any case.

To review the use of \verb|\include|, recall that the main file
\begin{verbatim}
  \documentclass{...}
  \includeonly{ch2}
  \begin{document}
    \include{ch1}
    \include{ch2}
    \include{ch3}
  \end{document}
\end{verbatim}
will process only the file \texttt{ch2.tex} as though the files
\texttt{ch1.tex} and \texttt{ch3.tex} were also present. That is, all
counters, especially the page and section numbers, as well as
cross-referencing definitions, will function as if the whole document
were processed. The trick is that each \verb|\include|d file has it own
\texttt{.aux} file containing these definitions, and they are all read
in every time, even if the corresponding \texttt{.tex} file is not. The
\texttt{.aux} files also contain the citation information for \BibTeX,
something that the \texttt{chapterbib} package exploits.

If \verb|\usepackage{chapterbib}| has been given, the keys in each
\verb|\cite| and \verb|\bibitem| command are associated with the
current \verb|\include|d file and are distinguished from the identical
key in a different file. Each of these files must contain its own
\verb|\bibliography| and \verb|\bibliographystyle| commands. One
processes \BibTeX\ on each file separately before processing it under
\LaTeX\ (at least twice).

\subsubsection{Special considerations for \textsf{natbib} and
\texttt{chapterbib}}
        
The \texttt{chapterbib} package provides an option \texttt{sectionbib}
that puts the bibliography in a \verb|\section*| instead of
\verb|\chapter*|, something that makes sense if there is a
bibliography in each chapter.  This option will not work when
\textsf{natbib} is also loaded; instead, add the option to
\textsf{natbib}. (The \texttt{sectionbib} option can always be given,
but it only has meaning for the \texttt{book} and \texttt{report}
classes, or for classes derived from them.)

Every \verb|\include|d file (with citations) must contain its own
\verb|\bibliography| command where the bibliography is to appear. The
database files listed as arguments to this command can be different in
each file, of course. However, what is not so obvious, is that each
file must also contain a \verb|\bibliographystyle| command,
\emph{preferably with the same style argument}. If different
bibliography styles are specified for different files, then the
preprogrammed citation style (punctuation and citation mode) will be
that of the first bibliography style given. The preprogrammed citation
styles can only be changed in the preamble (see
p.~\pageref{sec:priority}), something that guarantees a uniform style
for the entire document.\relax \footnote{It would be relatively easy
  to allow changes in style anywhere in the document, but this strikes
  me as bad policy. However, it is provided for with the
  \texttt{docstrip} option \texttt{nopreonly}.}

The order in which the \texttt{chapterbib} and \textsf{natbib}
packages are loaded is unimportant.
\subsection{Sorting and compressing numerical citations}
\label{sec:sort}

Another package by Donald Arseneau, \texttt{cite.sty}, reimplements the
entire (numerical) citation system such that one can control the
punctuation and citation format, all of which is done by \textsf{natbib} as
well. However, it also can sort and compress numerical citations,
something that is required by some journals. 

What this means is that when multiple citations are given with a single
\verb|\cite| command, the normal order of the numbers is in the sequence
given. This is usually a wild list of numbers, such as [4,2,8,3]. With
the \texttt{cite} package, this list becomes [2--4,8].

It is impossible to make the \texttt{cite} and \textsf{natbib}
packages compatible, since both reimplement \verb|\cite| from scratch.
Instead, I have taken over some of the coding from \texttt{cite.sty},
modifying it for \textsf{natbib}{}. This coding is activated by
including one of the options \texttt{sort} or \texttt{sort\&compress}
in the \verb|\usepackage| command.

For author--year citations, the option \texttt{sort} orders the
citations in a single \verb|\citep| or \verb|\citet| command into the
sequence in which they appear in the list of references. This is
normally alphabetical first, year second.  This should avoid citations
of the type: ``James et~al.\ (1994b,a)''. For author--year mode, the
\texttt{sort\&compress} option is identical to \texttt{sort}.

Do not use the \texttt{cite} package with \textsf{natbib}; rather use
one of the options \texttt{sort} or \texttt{sort\&compress}.  These
also work with author--year citations, making multiple citations
appear in the order they appear in the reference list.

\subsection{Long author list on first citation}\label{sec:long}

A feature that has often been requested by otherwise happy users of
\textsf{natbib} is one that is found in the \texttt{harvard} package as
standard: with the first citation of any reference, the full author
list is printed, and afterwards only the abbreviated list. One can
control this with \verb|\citet*| for the first citation, and
\verb|\citet| or \verb|\citep| thereafter.  However, the automatic
feature is very desirable.  This can be activated with the option
\texttt{longlistfirst}.

\subsubsection{Long author list on first citation}
Use option \texttt{longlistfirst} to have first citation automatically
give the full list of authors.  Suppress this for certain citations
with \verb|\shortcites{|\emph{key-list}\verb|}|, given before the first
citation.


\DescribeMacro{shortcites}
Some references have so many authors that you want to suppress the 
automatic long list only for them. In this case, issue
\begin{verbatim}
\shortcites{key-list}
\end{verbatim}
before the first citations, and those included in \emph{key-list} will have 
a short list on their first citation. 

Full author lists can still be forced at any time with the starred 
variants.

\section{Numerical citations with author--year styles}\label{sec:6.0}
In earlier versions, each \texttt{.bst} file could be used either for
numerical or author--year citation mode, without any possibility of
switching. Obviously numerical \texttt{.bst} files can never be used for
author--year citations (the information is missing in the auxiliary file)
but there is no reason why the converse should not work. 

I have been frequently asked if I could implement this feature, and I
at first replied that it would be quite easy. That was a mistake. The
numerical information was missing in the auxiliary files, so the
\verb|\cite| commands could never access it.  I have now recoded
\textsf{natbib}{} so that the separation of author and year
information comes before the information is written to the auxiliary
file, and furthermore, a sequential number is also written. This
permits numerical citations with \emph{any} of the author--year
bibliographic style files.

\subsection{Selecting numerical mode}
By default, \textsf{natbib}{} is in author--year mode. This can be
changed by
\begin{enumerate}
\item selecting a numerical bibliography style with predefined
  citation style, defined either in the package or in the local
  configuration file;
        
\item giving options \texttt{numbers} or \texttt{super} to the
  \verb|\usepackage| command;
        
\item issuing \verb|\bibpunct| with the 4th mandatory argument set to
  \texttt{n} or \texttt{s};
        
\item issuing \verb|\citestyle| with the name of a predefined
  numerical bibliography style.
\end{enumerate}
The methods are listed in order of increasing priority. 

The \textsf{natbib}{} package will automatically switch to numerical
mode if any one of the \verb|\bibitem| entries fails to conform to the
possible author--year formats. There is no way to override this, since
such an entry would cause trouble in the author--year mode.

There are certain special `numerical' styles, like that of the
standard \texttt{alpha.bst}, which include a non-numerical label in
place of the number, in the form
\begin{verbatim}
\bibitem[ABC95]{able95}
\end{verbatim}
As far as \textsf{natbib} is concerned, this label does not conform to the
author--year possibilities and is therefore considered to be numerical.
The citation mode switches to numerical, and \verb|\cite{able95}| prints
[ABC95].

\subsection{New bibliography styles}

I provide three new \texttt{.bst} files to replace the standard
\LaTeX\ numerical ones (\texttt{plainnat.bst}, \texttt{abbrvnat.bst}
and \texttt{unsrtnat.bst}.  These produce reference lists in the same
style as the corresponding standard \texttt{.bst} file, but can only
be used with \textsf{natbib}{}. The advantage is that they can be used
in both numerical and author--year mode.

In fact, \texttt{unsrtnat.bst} is rather silly for author--year
citations: the references are listed in the order they were cited,
which makes it difficult to find them. It is only included in case an
author wishes to switch from \texttt{plainnat} (author--year) to the
unsorted numerical mode, retaining the \verb|\citeauthor| and
\verb|\citeyear| commands in his paper.

It is not possible to produce a modified version of \texttt{alpha.bst}
since it would conflict with the \verb|\bibitem| format of
\textsf{natbib}.

\section{Local configuration}
For \LaTeXe, it is possible to add a local configuration file
\texttt{natbib.cfg}, which is read in, if it exists, at
the end of the package. It may thus contain coding to supecede that in
the package, although its main purpose is to allow the user to add his
own \verb|\bibstyle@|\textit{bst} definitions to couple citation punctuation
with local bibliography styles.

\end{Article}