path: root/Master/texmf-dist/doc/latex/natbib/natnotes.tex

%%
%% This is file `natnotes.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% natbib.dtx  (with options: `notes')
%% =============================================
%% IMPORTANT NOTICE:
%% 
%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License Distributed from CTAN
%% archives in directory macros/latex/base/lppl.txt; either
%% version 1 of the License, or any later version.
%% 
%% This is a generated file.
%% It may not be distributed without the original source file natbib.dtx.
%% 
%% This is a Reference Sheet for natbib. It consists of excerpts from the
%% original source file.
%% 
%% For more details, LaTeX the source 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}
\def\DescribesFile#1 [#2 #3 #4]
  {\def\filename{#1}\def\filedate{#2}\def\fileversion{#3}}
\DescribesFile{natbib}
        [2009/07/16 8.31 (PWD, AO)]
\documentclass{article}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}
\setlength{\textwidth}{\paperwidth}
\addtolength{\textwidth}{-2in}
\setlength{\oddsidemargin}{0pt}
\setlength{\textheight}{\paperheight}

\addtolength{\textheight}{-\headheight}
\addtolength{\textheight}{-\headsep}
\addtolength{\textheight}{-\footskip}
\addtolength{\textheight}{-2in}
\makeatletter
\def\@listI{\leftmargin\leftmargini
  \topsep\z@ \parsep\parskip \itemsep\z@}
\let\@listi\@listI
\@listi
\makeatother
\newcommand{\head}[1]{\subsubsection*{#1}}

\pagestyle{headings}
\markright{Reference sheet: \texttt{natbib}}

\usepackage{shortvrb}
\MakeShortVerb{\|}

\begin{document}
\thispagestyle{plain}

\newcommand{\btx}{\textsc{Bib}\TeX}
\newcommand{\thestyle}{\texttt{\filename}}
\begin{center}{\bfseries\Large
    Reference sheet for \thestyle\ usage}\\
    \large(Describing version \fileversion\ from \filedate)
\end{center}

\begin{quote}\slshape
For a more detailed description of the \thestyle\ package, \LaTeX\ the
source file \thestyle\texttt{.dtx}.
\end{quote}
\head{Overview}
The \thestyle\ package is a reimplementation of the \LaTeX\ |\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 \thestyle.

\head{Loading}
Load with |\usepackage[|\emph{options}|]{|\thestyle|}|. See list of
\emph{options} at the end.

\head{Replacement bibliography styles}
I provide three new \texttt{.bst} files to replace the standard \LaTeX\
numerical ones:
\begin{quote}\ttfamily
 plainnat.bst \qquad abbrvnat.bst \qquad unsrtnat.bst
\end{quote}
\head{Basic commands}
The \thestyle\ package has two basic citation commands, |\citet| and
|\citep| for \emph{textual} and \emph{parenthetical} citations, respectively.
There also exist the starred versions |\citet*| and |\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{quote}
\begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
  |\citet{jon90}| & Jones et al. (1990)\\
  |\citet[chap.~2]{jon90}| & Jones et al. (1990, chap.~2)\\[0.5ex]
  |\citep{jon90}| & (Jones et al., 1990)\\
  |\citep[chap.~2]{jon90}| & (Jones et al., 1990, chap.~2)\\
  |\citep[see][]{jon90}| & (see Jones et al., 1990)\\
  |\citep[see][chap.~2]{jon90}| & (see Jones et al., 1990, chap.~2)\\[0.5ex]
  |\citet*{jon90}| & Jones, Baker, and Williams (1990)\\
  |\citep*{jon90}| & (Jones, Baker, and Williams, 1990)
\end{tabular}
\end{quote}
\head{Multiple citations}
Multiple citations may be made by including more than one
citation key in the |\cite| command argument.
\begin{quote}
\begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
  |\citet{jon90,jam91}| & Jones et al. (1990); James et al. (1991)\\
  |\citep{jon90,jam91}| & (Jones et al., 1990; James et al. 1991)\\
  |\citep{jon90,jon91}| & (Jones et al., 1990, 1991)\\
  |\citep{jon90a,jon90b}| & (Jones et al., 1990a,b)
\end{tabular}
\end{quote}

\head{Numerical mode}
These examples are for author--year citation mode. In numerical mode, the
results are different.
\begin{quote}
\begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
  |\citet{jon90}| & Jones et al. [21]\\
  |\citet[chap.~2]{jon90}| & Jones et al. [21, chap.~2]\\[0.5ex]
  |\citep{jon90}| & [21]\\
  |\citep[chap.~2]{jon90}| & [21, chap.~2]\\
  |\citep[see][]{jon90}| & [see 21]\\
  |\citep[see][chap.~2]{jon90}| & [see 21, chap.~2]\\[0.5ex]
  |\citep{jon90a,jon90b}| & [21, 32]
\end{tabular}
\end{quote}
\head{Suppressed parentheses}
As an alternative form of citation, |\citealt| is the same as |\citet| but
\emph{without parentheses}. Similarly, |\citealp| is |\citep| without
parentheses.

The |\citenum| command prints the citation number, without parentheses, even
in author--year mode, and without raising it in superscript mode. This is
intended to be able to refer to citation numbers without superscripting them.

\begin{quote}
\begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
  |\citealt{jon90}| & Jones et al.\ 1990\\
  |\citealt*{jon90}| & Jones, Baker, and Williams 1990\\
  |\citealp{jon90}| & Jones et al., 1990\\
  |\citealp*{jon90}| & Jones, Baker, and Williams, 1990\\
  |\citealp{jon90,jam91}| & Jones et al., 1990; James et al., 1991\\
  |\citealp[pg.~32]{jon90}| & Jones et al., 1990, pg.~32\\
  |\citenum{jon90}| & 11\\
  |\citetext{priv.\ comm.}| & (priv.\ comm.)
\end{tabular}
\end{quote}
The |\citetext| command
allows arbitrary text to be placed in the current citation parentheses.
This may be used in combination with |\citealp|.
\head{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{quote}
\begin{tabular}{l@{\quad$\Rightarrow$\quad}l}
  |\citeauthor{jon90}| & Jones et al.\\
  |\citeauthor*{jon90}| & Jones, Baker, and Williams\\
  |\citeyear{jon90}|   & 1990\\
  |\citeyearpar{jon90}| & (1990)
\end{tabular}
\end{quote}
\head{Forcing upper cased names}
If the first author's name contains a \textsl{von} part, such as ``della
Robbia'', then |\citet{dRob98}| produces ``della Robbia (1998)'', even at the
beginning of a sentence. One can force the first letter to be in upper case
with the command |\Citet| instead. Other upper case commands also exist.
\begin{quote}
\begin{tabular}{rl@{\quad$\Rightarrow$\quad}l}
  when & |\citet{dRob98}| & della Robbia (1998) \\
  then & |\Citet{dRob98}| & Della Robbia (1998) \\
     &   |\Citep{dRob98}| & (Della Robbia, 1998) \\
     &   |\Citealt{dRob98}| & Della Robbia 1998 \\
     &   |\Citealp{dRob98}| & Della Robbia, 1998 \\
     &   |\Citeauthor{dRob98}| & Della Robbia
\end{tabular}
\end{quote}
These commands also exist in starred versions for full author names.

\head{Citation aliasing}
Sometimes one wants to refer to a reference with a special designation,
rather than by the authors, i.e. as Paper~I, Paper~II. Such aliases can be
defined and used, textual and/or parenthetical with:
\begin{quote}
\begin{tabular}{lcl}
  |\defcitealias{jon90}{Paper~I}|\\
  |\citetalias{jon90}| & $\Rightarrow$ & Paper~I\\
  |\citepalias{jon90}| & $\Rightarrow$ & (Paper~I)
\end{tabular}
\end{quote}
These citation commands function much like |\citet| and |\citep|: they may
take multiple keys in the argument, may contain notes, and are marked as
hyperlinks.
\head{Selecting citation style and punctuation}
Use the command |\setcitestyle| with a list of comma-separated
keywords (without spaces) as argument.
\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}|}|
  %^^A \NAT@cmt
\end{itemize}
Defaults are |authoryear|, |round|, |comma|, |aysep={;}|, |yysep={,}|,
|notesep={, }|

Example~1, |\setcitestyle{square,aysep={},yysep={;}}| changes the author--year
output of
\begin{quote}
  |\citep{jon90,jon91,jam92}|
\end{quote}
into [Jones et al. 1990; 1991, James et al. 1992].

Example~2, |\setcitestyle{notesep={; },round,aysep={},yysep={;}}| changes the output of
\begin{quote}
  |\citep[and references therein]{jon90}|
\end{quote}
into (Jones et al. 1990; and references therein).

\head{Other formatting options}
Redefine |\bibsection| to the desired sectioning command for introducing
the list of references. This is normally |\section*| or |\chapter*|.

Redefine |\bibpreamble| to be any text that is to be printed after the heading but
before the actual list of references.

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

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
the list of references. The default definition is |[#1]|.

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

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

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

\head{Use with \texttt{chapterbib} package}

The \thestyle\ package is compatible with the \texttt{chapterbib} package
which makes it possible to have several bibliographies in one document.

The package makes use of the |\include| command, and each |\include|d file
has its own bibliography.

The order in which the \texttt{chapterbib} and \thestyle\ packages are loaded
is unimportant.

The \texttt{chapterbib} package provides an option \texttt{sectionbib}
that puts the bibliography in a |\section*| instead of |\chapter*|,
something that makes sense if there is a bibliography in each chapter.
This option will not work when \thestyle\ is also loaded; instead, add
the option to \thestyle.

Every |\include|d file must contain its own
|\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 |\bibliographystyle| command, with possibly differing arguments.

As of version~8.0, the citation style, including mode (author--year or
numerical) may also differ between chapters. The |\setcitestyle| command
can be issued at any point in the document, in particular in different
chapters.
\head{Sorting and compressing citations}
Do not use the \texttt{cite} package with \thestyle; rather use one of the
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.

Suppress this for certain citations with |\shortcites{|\emph{key-list}|}|,
given before the first citation.

\head{Local configuration}
Any local recoding or definitions can be put in \thestyle\texttt{.cfg} which
is read in after the main package file.

\head{Options that can be added to \texttt{\char`\\ usepackage}}
\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 semicolon] (default) to separate multiple citations with
     semi-colons;
\item[\ttfamily colon] the same as \texttt{semicolon}, an earlier mistake in
     terminology;
\item[\ttfamily comma] to use commas as separators;
\item[\ttfamily authoryear] (default) for author--year citations;
\item[\ttfamily numbers] for numerical citations;
\item[\ttfamily super] for superscripted numerical citations, as in
     \textsl{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 compress] to compress without sorting, so compression only
     occurs when the given citations would produce an ascending sequence of
     numbers;
\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 |\thebibliography| to issue
     |\section*| instead of |\chapter*|; valid only for classes with a
     |\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;
\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.tex'.