cite.sty update (14apr09)

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

1 files changed, 255 insertions, 131 deletions

diff --git a/Master/texmf-dist/tex/latex/cite/cite.sty b/Master/texmf-dist/tex/latex/cite/cite.sty
index 5444e23f930..70ea664909a 100644
--- a/Master/texmf-dist/tex/latex/cite/cite.sty
+++ b/Master/texmf-dist/tex/latex/cite/cite.sty
@@ -1,12 +1,12 @@
 %     C I T E . S T Y
 %
-%     version 4.01  (Nov 2003)
+%     version 5.0  (Mar 2009)
 %
 %     Compressed, sorted lists of on-line or superscript numerical citations.
 %     see also drftcite.sty (And the stub overcite.sty)
 %
-%     Copyright (C) 1989-2003 by Donald Arseneau
-%     These macros may be freely transmitted, reproduced, or modified
+%     Copyright (C) 1989-2009 by Donald Arseneau
+%     These macros may be freely used, transmitted, reproduced, or modified
 %     provided that this notice is left intact.
 %
 %     Instructions follow \endinput.
@@ -37,14 +37,20 @@
 \providecommand\citeright{]}
 
 %   , (comma space) before note
-\providecommand\citemid{,\penalty\@medpenalty\ }
+\providecommand\citemid{,\penalty\citemidpenalty\ }
 
 %   , (comma thin-space) between entries; [nospace] eliminates the space
-\providecommand\citepunct{,\penalty\@m\hskip.13emplus.1emminus.1em}%
+\providecommand\citepunct{,\penalty\citepunctpenalty%
+        \hskip.13emplus.1emminus.1em\relax}%
 
 %   -- (endash) designating range of numbers:
 % (using \hbox avoids easy \exhyphenpenalty breaks)
-\providecommand{\citedash}{\hbox{--}\penalty\@m}
+\providecommand{\citedash}{\hbox{--}\penalty\citepunctpenalty}
+
+% Default line-breaking penalties. Use \mathchardef instead of count registers
+\mathchardef\citeprepenalty=\@highpenalty
+\mathchardef\citemidpenalty=\@medpenalty
+\mathchardef\citepunctpenalty=\@m
 
 %   Each number left as-is:
 \providecommand\citeform{}
@@ -69,79 +75,157 @@
 % compress ranges of numbers and print the list. \citen can be used by itself
 % to give citation numbers without the brackets and other formatting; e.g.,
 % "See also ref.~\citen{junk}."
+%  Make internal version called \@cite@n just in case packages put hooks in
+%  \citen
 %
-\DeclareRobustCommand\citen[1]{%
+\DeclareRobustCommand\citen{\@cite@n}
+\def\@cite@n#1{%
  \begingroup
   \let\@safe@activesfalse\@empty
   \@nocite{#1}% ignores spaces, writes to .aux file, returns #1 in \@no@sparg
   \@tempcntb\m@ne    % \@tempcntb tracks highest number
-  \let\@h@ld\@empty  % nothing held from list yet
-  \let\@citea\@empty % no punctuation preceding first
   \let\@celt\delimiter % an unexpandable, but identifiable, token
   \def\@cite@list{}% % empty list to start
+  \let\@citea\@empty % no punctuation preceding first
   \@for \@citeb:=\@no@sparg\do{\@make@cite@list}% make a sorted list of numbers
   % After sorted citelist is made, execute it to compress citation ranges.
   \@tempcnta\m@ne    % no previous number
+  \mathchardef\@cite@incr\z@ % no previous sequence
+  \let\@h@ld\@empty  % nothing held from list yet
   \let\@celt\@compress@cite \@cite@list % output number list with compression
   \@h@ld % output anything held over
  \endgroup
  \@restore@auxhandle
  }
 
-% For each citation, check if it is defined and if it is a number.
-% if a number: insert it in the sorted \@cite@list
-% otherwise: output it immediately.
+% For each citation, check if it is defined. If so, then extract plain
+% value to \@B@citeB (without hyperlink info). Then, 
+% If it is a pure number, add it to cite list
+% Otherwise, try extracting prefix and suffix characters.
 %
 \def\@make@cite@list{%
- \expandafter\let \expandafter\@B@citeB
-          \csname b@\@citeb\@extra@b@citeb \endcsname
- \ifx\@B@citeB\relax % undefined: output ? and warning
+ \expandafter\ifx\csname b@\@citeb\@extra@b@citeb 
+      \endcsname\relax % undefined: output ? and warning
     \@citea {\bfseries ?}\let\@citea\citepunct \G@refundefinedtrue
     \@warning {Citation `\@citeb' on page \thepage\space undefined}%
-    \oc@verbo \global\@namedef{b@\@citeb\@extra@b@citeb}{?}%
+ %%   \oc@verbo \global\@namedef{b@\@citeb\@extra@b@citeb}{?}%  ???
  \else %  defined               % remove previous line to repeat warnings
+    \begingroup \let\hyper@@link\@nonhyper@@link
+    \protected@xdef\@B@citeB{\csname b@\@citeb\@extra@b@citeb \endcsname}%
+    \endgroup
     \ifcat _\ifnum\z@<0\@B@citeB _\else A\fi % a positive number, put in list
-       \@addto@cite@list
-    \else % citation is not a number, output immediately
-       \@citea \citeform{\@B@citeB}\let\@citea\citepunct
+       \@addnumto@cite@list\@B@citeB
+    \else %citation is not a simple number, try letter-number or number-letter
+       \expandafter \@cite@add@letnum \@B@citeB\delimitershortfall\delimiter
  \fi\fi}
 
-% Regular definition for adding entry to cite list, with sorting
+\def\@nonhyper@@link [#1]#2#3#4{#4}
+
+\def\@cite@out#1{\citeform{\csname #1\endcsname}}
+
+% first stage for sorting values with prefix/suffix characters.  #1 is the
+% first character: a digit or a prefix.
+% The numeric sort value (\@tempcnta) is ((prefix*16384+number)*256+suffix.
+% 
+\def\@cite@add@letnum#1#2\delimiter{%
+  \ifcat _\ifnum\z@<0#1_\else A\fi % test the first character for a digit
+     \@cite@add@LETnum\z@{#1#2}%
+  \else % first char is non-digit, use ascii value
+     \@cite@add@LETnum{`#1}{#2}%
+  \fi}
+
+% second stage for sorting values with prefix/suffix characters, #1 is prefix
+% as a number, #2 is the rest.  Pull out numeric portion from the rest.
+\def\@cite@add@LETnum#1#2{%
+  \@tempcnta=#1\multiply\@tempcnta 16384 %
+  \afterassignment\@cite@add@letnumlet  \advance\@tempcnta 0#2\delimiter
+}
 
-\def\@addto@cite@list{\@tempcnta\@B@citeB \relax
+% third stage for sorting values with prefix/suffix characters (gets suffix)
+\def\@cite@add@letnumlet#1#2\delimiter{%
+  \multiply\@tempcnta\@cclvi
+  \ifx \delimiter#1\delimiter % Trailing empty arg like {}
+    \@citeaddcnta
+  \else
+    \ifx \delimitershortfall#1\relax % no trailing token
+      \@citeaddcnta
+    \else % got a trailing character
+      \toks@={#2}%
+      \ifx\delimitershortfall#2\relax % got just one trailing character
+        \advance\@tempcnta`#1\relax
+        \@citeaddcnta
+      \else % else, can't be sorted, so output immediately
+        \@citea \@cite@out{\@citeb\@extra@b@citeb}\let\@citea\citepunct
+      \fi
+    \fi
+  \fi}
+
+% add pure numeric entry to cite list, with sorting
+\def\@addnumto@cite@list#1{%
+   \@tempcnta#1\relax
+   \multiply\@tempcnta\@cclvi
+   \@citeaddcnta}
+
+% add an entry to the sorted list, using its sort-number \@tempcnta, and
+% also saving the plain-text value \@B@citeB as well as the csname 
+% b@\@citeb\@extra@b@citeb. (The \@B@citeB is actually not used, unless 
+% somebody needs to modify it.)
+\def\@citeaddcnta{%
    \ifnum \@tempcnta>\@tempcntb % new highest, add to end (efficiently)
-      \edef\@cite@list{\@cite@list \@celt{\@B@citeB}}%
+      \edef\@cite@list{\@cite@list 
+        \@celt{\number\@tempcnta}{\@B@citeB}{b@\@citeb\@extra@b@citeb}}%
       \@tempcntb\@tempcnta
-   \else % arbitrary number: insert appropriately
-      \edef\@cite@list{\expandafter\@sort@celt \@cite@list \@gobble @}%
-   \fi}
+   \else % other sortable value: insert appropriately
+      \edef\@cite@list{\expandafter\@sort@celt\@cite@list \@gobble.\@gobble.}%
+   \fi
+  }
 %
-% \@sort@celt inserts number (\@tempcnta) into list of \@celt{num} (#1{#2})
-% \@celt must not be expandable; list should end with two vanishing tokens.
+% \@sort@celt inserts number (\@tempcnta) into list of \@celt{num}{text}{tag} 
+% (#1{#2}{#3}{#4})
+% \@celt must not be expandable, and the arguments must not be fragile. 
+% List should end with four vanishing tokens.
 %
-\def\@sort@celt#1#2{\ifx \@celt #1% parameters are \@celt {num}
+\def\@sort@celt#1#2#3#4{\ifx \@celt #1% parameters are \@celt{num}{text}{tag}
    \ifnum #2<\@tempcnta % number goes later in list
-      \@celt{#2}%
+      \@celt{#2}{#3}{#4}%
       \expandafter\expandafter\expandafter\@sort@celt % continue
    \else % number goes here
-      \@celt{\number\@tempcnta}\@celt{#2}% stop comparing
+      \@celt{\number\@tempcnta}{\@B@citeB}{b@\@citeb\@extra@b@citeb}%
+      \@celt{#2}{#3}{#4}% stop comparing
 \fi\fi}
 
-% Check if each number follows previous and can be put in a range
+% Check if each number follows previous and can be put in a range. 
+% Since there are suffix characters allowed, there are two kinds of 
+% ranges: ranges of consecutive pure numbers with no (or same) 
+% suffix, or ranges of the same number with consecutive suffix
+% characters.
 %
-\def\@compress@cite#1{%  % This is executed for each number
-  \advance\@tempcnta\@ne % Now \@tempcnta is one more than the previous number
-  \ifnum #1=\@tempcnta   % Number follows previous--hold on to it
-     \ifx\@h@ld\@empty   % first pair of successives
-        \expandafter\def\expandafter\@h@ld\expandafter{\@citea 
-           \citeform{#1}}%
-     \else               % compressible list of successives
-        \def\@h@ld{\citedash \citeform{#1}}%
-     \fi
-  \else   %  non-successor -- dump what's held and do this one
-     \@h@ld \@citea \citeform{#1}%
-     \let\@h@ld\@empty
-  \fi \@tempcnta#1\let\@citea\citepunct
+\def\@compress@cite#1#2#3{%% This is executed for each number
+  \ifnum\@cite@incr=\z@   % no consecutives pending. Try both types of sequence
+    \advance\@tempcnta\@cclvi % Now \@tempcnta has incremented number
+    \ifnum #1=\@tempcnta    % Start a sequence of consecutive numbers
+       \expandafter\def\expandafter\@h@ld\expandafter{\@citea\@cite@out{#3}}%
+       \mathchardef\@cite@incr=\@cclvi
+    \else % next try increment of suffix
+       \advance\@tempcnta-\@cclv % Now \@tempcnta has incremented suffix
+       \ifnum #1=\@tempcnta      % Start a sequence of suffix increments
+         \expandafter\def\expandafter\@h@ld\expandafter{\@citea\@cite@out{#3}}%
+         \mathchardef\@cite@incr=\@ne
+       \else % it is no type of sequence -- emit number (nothing is held)
+         \@citea \@cite@out{#3}%
+       \fi
+    \fi
+  \else % a sequence is running
+    \advance\@tempcnta\@cite@incr % Now \@tempcnta is next in sequence
+    \ifnum #1=\@tempcnta   % Number follows previous--hold on to it
+       \def\@h@ld{\citedash \@cite@out{#3}}%
+    \else   %  non-successor -- dump what's held and do this one
+       \@h@ld \@citea \@cite@out{#3}%
+       \let\@h@ld\@empty
+       \mathchardef\@cite@incr=\z@
+    \fi
+  \fi
+  \@tempcnta#1\let\@citea\citepunct
 }
 
 % Make \cite choose superscript or normal
@@ -151,7 +235,7 @@
 
 % Do \cite command on line.
 %
-\def\@citex[#1]#2{\@cite{\citen{#2}}{#1}}
+\def\@citex[#1]#2{\@cite{\@cite@n{#2}}{#1}}
 
 \def\@cite#1#2{\leavevmode \cite@adjust
   \citeleft{#1\if@tempswa\@safe@activesfalse\citemid{#2}\fi
@@ -165,7 +249,7 @@
 %
 \def\cite@adjust{\begingroup%
   \@tempskipa\lastskip \edef\@tempa{\the\@tempskipa}\unskip
-  \ifnum\lastpenalty=\z@ \penalty\@highpenalty \fi
+  \ifnum\lastpenalty=\z@ \penalty\citeprepenalty \fi
   \ifx\@tempa\@zero@skip \spacefactor1001 \fi % if no space before, set flag
   \ifnum\spacefactor>\@m \ \else \hskip\@tempskipa \fi
   \endgroup}
@@ -179,7 +263,7 @@
   \@if@fillglue \lastskip \relax \unskip
   \def\@tempa{\@tempcnta\spacefactor
      \/% this allows the last word to be hyphenated, and it looks better.
-     \@citess{\citen{#1}}\spacefactor\@tempcnta
+     \@citess{\@cite@n{#1}}\spacefactor\@tempcnta
      \endgroup \@restore@auxhandle}%
   \oc@movep\relax}% check for following punctuation (depending on options)
 
@@ -188,12 +272,18 @@
 \def\@citey{\let\@tempc\@tempa
    % Watch for double periods and suppress them
    \ifx\@tempb.\ifnum\spacefactor<\@bigSfactor\else
-     \let\@tempb\relax \let\@tempc\oc@movep
+     \@citeundouble
    \fi\fi
    % Move other punctuation
    \expandafter\@citepc\CiteMoveChars\delimiter
    \@tempc}%
 
+% This is in a separate macro in case the next "character" (token)
+% is \if or \fi, etc.
+\def\@citeundouble{% Suppress doubling of periods
+   \let\@tempb\relax \let\@tempc\oc@movep
+}
+
 \def\@citepc#1{%
    \ifx\@tempb#1\@empty #1\let\@tempc\oc@movep \fi
    \ifx\delimiter#1\else \expandafter\@citepc\fi}
@@ -209,18 +299,19 @@
 
 % \nocite: This is changed to ignore *ALL* spaces and be robust.  The
 % parameter list, with spaces removed, is `returned' in \@no@sparg, which
-% is used by \citen.
+% is used by \@cite@n (\citen).
 %
 \DeclareRobustCommand\nocite[1]{%
  \@bsphack \@nocite{#1}%
  \@for \@citeb:=\@no@sparg\do{\@ifundefined{b@\@citeb\@extra@b@citeb}%
     {\G@refundefinedtrue\@warning{Citation `\@citeb' undefined}%
-    \oc@verbo \global\@namedef{b@\@citeb\@extra@b@citeb}{?}}{}}%
+    %%\oc@verbo \global\@namedef{b@\@citeb\@extra@b@citeb}{?}
+    }{}}%
  \@esphack}
 
 \def\@nocite#1{\begingroup\let\protect\string% normalize active chars
  \xdef\@no@sparg{\expandafter\@ignsp#1 \: }\endgroup% and remove ALL spaces
- \if@filesw \immediate\write\@newciteauxhandle % = \@auxout, except with multibib
+ \if@filesw \immediate\write\@newciteauxhandle % =\@auxout, except with multibib
     {\string\citation {\@no@sparg}}\fi
  }
 
@@ -243,20 +334,17 @@
 
 \let\nocitecount\relax  % in case \nocitecount was used for drftcite
 
-% For the time being, just prevent gross errors from using hyperref.
-% There are no hyper-links.  (I will need to carry the cite tags through
-% the sorting process, and use \hyper@natlinkstart)
-
-\providecommand\hyper@natlinkstart[1]{}
-\providecommand\hyper@natlinkend{}
-\providecommand\NAT@parse{\@firstofone}
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %                     option processing
 
 \DeclareOption{verbose}{\def\oc@verbo#1#2#3#4{}}
-\DeclareOption{nospace}{\def\citepunct{,\penalty\@m}}
-\DeclareOption{space}{\def\citepunct{,\penalty\@highpenalty\ }}
+\DeclareOption{nospace}{\def\citepunct{,\penalty\citepunctpenalty}}
+\DeclareOption{space}{\def\citepunct{,\penalty\citepunctpenalty\ }}
+\DeclareOption{nobreak}{% no line-breaks
+ \mathchardef\citeprepenalty=\@M
+ \mathchardef\citemidpenalty=\@M
+ \mathchardef\citepunctpenalty=\@M
+}
 \DeclareOption{ref}{\def\citeleft{[Ref.\penalty\@M\ }}
 \DeclareOption{nosort}{\def\@addto@cite@list
    {\edef\@cite@list{\@cite@list \@celt{\@B@citeB}}}}
@@ -264,8 +352,8 @@
 \DeclareOption{nomove}{\def\oc@movep{\@tempa}\let\@citey\oc@movep}
 \DeclareOption{move}{}% default
 \DeclareOption{nocompress}{%
-  \def\@compress@cite#1{%  % This is executed for each number
-     \@h@ld \@citea \hyper@natlinkstart\citeform{#1}\hyper@natlinkend
+  \def\@compress@cite#1#2#3{%  % This is executed for each number
+     \@h@ld \@citea \@cite@out{#3}%
      \let\@h@ld\@empty \let\@citea\citepunct}
 }
 \DeclareOption{compress}{}% default
@@ -277,7 +365,7 @@
 \DeclareOption{noadjust}{\let\cite@adjust\@empty}% Don't change spaces
 \DeclareOption{adjust}{}% adjust space before [ ]
 \DeclareOption{biblabel}{\def\@biblabel#1{\@citess{#1}\kern-\labelsep\,}}
-\ProvidesPackage{cite}[2003/11/04 \space  v 4.01]
+\ProvidesPackage{cite}[2009/03/20 \space v 5.0x]
 \ProcessOptions
 
 \ifx\@citey\oc@movep\else % we are moving punctuation; must ensure sfcodes
@@ -299,19 +387,30 @@
 \AtBeginDocument{\@ifundefined{newcites}{\global\let\@restore@auxhandle\relax}{}}
 \def\@restore@auxhandle{\def\@newciteauxhandle{\@auxout}}
 
-
+%  compatability with backref: prevent it from redefining \@citex
+%  in the wrong way (ignoring \@citew and \citen.  I install hook in
+%  \@nocite so it applies everywhere, even \nocite!
+%
+\AtBeginDocument{\@ifundefined{Hy@backout}{}{
+  \@ifundefined{BRorg@citex}{}{\global\let\@citex\BRorg@citex}%
+  \global\let\BR@citex\@citex
+  \global\let\@citeorg@nocite\@nocite % use my own hook -> into \@nocite
+  \gdef\@nocite#1{\@citeorg@nocite{#1}\Hy@backout{#1}}%
+}}
+
+%  compatability with ooold LaTeX
 \@ifundefined{G@refundefinedtrue}{\let\G@refundefinedtrue\relax}{}
 
-\@ifundefined{@safe@activesfalse}{}{}
+%  compatability with babel:  Prevent it from redefining \@citex
+\@ifundefined{@safe@activesfalse}{\let\@safe@activesfalse\relax}{}
 \@ifundefined{bbl@cite@choice}{}{\@ifundefined{org@@citex}{}%
   {\let\org@@citex\@citex}}% Prevent stomping by babel
 
-
 \citenum % execute restore-catcodes
 
 % Aliases:
-\let\citenum\citen
-\let\citeonline\citen
+\def\citenum{\citen}
+\def\citeonline{\citen}
 
 \endinput
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -319,7 +418,7 @@
 
                    CITE.STY
 
-Modify LaTeX's normal citation mechanism to:
+Modify LaTeX's normal citation mechanism to behave as follows:
 
 o Put a comma and a small space between each citation number. The option
   [nospace] removes that space, and the option [space] replaces it with
@@ -335,62 +434,70 @@ o Compress lists of three or more consecutive numbers to one number range
   [7,5,6,?,4,9,8,Einstein,6], then this style will give [?,Einstein,4-6,6-9].
   Compression of ranges is disabled by the [nocompress] package option.
 
-o Allow, but strongly discourage, line breaks within a series of
-  citations.  Each number is separated by a comma and a small space.
-  A break at the beginning of an optional note is discouraged also.
+o Sort numeric citations with prefix and/or suffix characters so different 
+  prefixes are grouped together, and suffixes form sub-lists for the same
+  number; so you could get  [18a-18c,19] or [A48,Q1,Q3-Q5].
+
+o Allow, but discourage, line breaks within the group of citations (after
+  dashes, and after punctuation). Penalties are \citepunctpenalty and
+  \citemidpenalty. 
 
-o Put a high-penalty breakpoint before the citation (unless you specifically
-  forbid it with ~ ).  Also, adjust the spacing: if there is no space or if
-  there is extra space due to some punctuation, then change to one inter-word
-  space. E.g.,   A space will be inserted here\cite{Larry,Curly,Moe}.
+o Put a high-penalty breakpoint (value \citeprepenalty) before the citation 
+  (unless there is a different penalty specified there).  Also, adjust the 
+  spacing: if there is no space or if there is extra space due to some 
+  punctuation, then change to one inter-word space. E.g.,   
+  A space will be inserted here\cite{Larry,Curly,Moe}.
+
+o All breaks can be forbidden with the [nobreak] package option.  They can 
+  be adjusted independently by setting the parameters \citeprepenalty, 
+  \citemidpenalty, and \citepunctpenalty.  Use \mathchardef to change these
+  penalty values!  E.g.,  \mathchardef\citeprepenalty=9999 (Yes, that is 
+  obscure but I don't want to pretend they are counters.)
 
 o With package option [superscript] (or [super] for short), display citation
   numbers as superscripts (unless they have optional notes, causing them to
-  be treated as described above).  Superscripted citations follow these
+  be printed on-line with brackets).  Superscripted citations follow these
   additional rules:
 
-- Superscript citations use THE SAME INPUT FORMAT as ordinary citations; this
-  style will ignore spaces before the citation, and move trailing punctuation
-  before the superscript citation.  For example, "information \cite{source};"
-  ignores the space before \cite and puts the semicolon before the number, just
-  as if you had typed "information;$^{12}$".  You may switch off movement with
-  the [nomove] package option (only relevant with [superscript]).
-
-- The punctuation characters that will migrate before the superscript are
-  listed in the macro \CiteMoveChars, which you can redefine.  The default is
-  .,;:.   Perhaps ! and ? should too, but they weren't listed in the APS style
-  manual I looked at, and I agree with that rule to prevent too much visual
-  separation.  Quotes were listed, but they should never have to migrate
-  because both on-line and superscript versions put quotes before the citation.
-  This gives one difficulty --- punctuation following quotes won't migrate
-  inside the quotation: e.g., "``Transition State Theory''\cite{Eyring}." gives
-  "``Transition State Theory''.$^8$", but you may want the period inside the
-  quotes, thus: ``Transition State Theory.''$^8$.
-
-- Doubling of periods (.., ?., !.) is checked for and suppressed. The spacing
-  after the citation is set according to the final punctuation mark moved.
-  There is a problem with double periods after a capitalized abbreviation
-  or directly after \@ : Both of "N.A.S.A. \cite{space}." and "et al.\@
-  \cite{many}." will give doubled periods.  These can be fixed as follows:
-  "N.A.S.A\@. \cite{space}." and "et al.\ \cite{many}.". The NASA example 
-  gives the wrong spacing when there is no citation.  Sorry.  Use \  after
-  abbreviations like et al. to get the right spacing within a sentence whether
-  or not a citation follows.
-
-- Remember, these rules regarding punctuation only apply when the [superscript]
-  option was given (or overcite.sty used) and the [nomove] option was NOT
-  given.
+-> Superscript citations use THE SAME INPUT FORMAT as ordinary citations; this
+   style will ignore spaces before the citation, and move trailing punctuation
+   before the superscript citation.  For example, "information \cite{source};"
+   ignores the space before \cite and puts the semicolon before the number,
+   just as if you had typed "information;$^{12}$".  You may switch off movement
+   with the [nomove] package option (only relevant with [superscript]).
+
+-> The punctuation characters that will migrate before the superscript are
+   listed in the macro \CiteMoveChars, which you can redefine.  The default is
+   .,;:.   Perhaps ! and ? should too, but they weren't listed in the APS style
+   manual I looked at, and I agree with that choice because they put too
+   much visual separation between the cite and what it applies to.  Feel free
+   to redefine \CiteMoveChars.  Quotes were listed as coming before the
+   cite notation, but they should be typed before the \cite command in any
+   case because both on-line and superscript cites come after the quotation. 
+   This gives one difficulty --- punctuation following quotes won't migrate
+   inside the quotation: e.g., "``Transition State Theory''\cite{Eyring}." 
+   gives "``Transition State Theory''.$^8$", but you may want the period inside
+   the quotes, thus: ``Transition State Theory.''$^8$.
+
+-> Doubling of periods (.., ?., !.) is checked for and suppressed. The spacing
+   after the citation is set according to the final punctuation mark moved.
+   There is a problem with double periods after a capitalized abbreviation
+   or directly after \@ : Both of "N.A.S.A. \cite{space}." and "et al.\@
+   \cite{many}." will give doubled periods.  These can be fixed as follows:
+   "N.S.A\@. \cite{space}." and "et al.\ \cite{many}.". The NSA example 
+   gives the wrong spacing when there is no citation.  Sorry.  Use \  after
+   abbreviations like et al. to get the right spacing within a sentence whether
+   or not a citation follows.
+
+-> Remember, these rules regarding punctuation only apply when the [super]
+   or [superscript] option was given (or overcite.sty used) and the [nomove]
+   option was NOT given.
 
 o Define \citen to get just the numbers without the brackets or superscript
   and extra formatting.  Aliases are \citenum and \citeonline for easy
   conversion to other citation packages.
 
-o `Citation...undefined' warnings are only given once per undefined citation
-  tag.  In the text, missing numbers are represented with a bold `?' at the
-  first occurrence, and with a normal `?' thenceforth.  The package option
-  [verbose] restores the usual repeated warnings.
-
-o Make \nocite, \cite, and \citen all ignore spaces in the input tags.
+o All of \nocite, \cite, and \citen ignore spaces in the input tags.
 
 Although each \cite command sorts its numbers, better compression into
 ranges can usually be achieved by carefully selecting the order of the
@@ -404,12 +511,13 @@ There are several options for \usepackage{cite}, some already mentioned.
 
  [superscript] use superscrpts for cites without optional notes
  [super]       alias for [superscript] (like natbib)
- [verbose]     causes warnings for undefined cites to be repeated each time
- [ref]         uses the format "[Ref.~12, optional note]" (useful with 
+ [verbose]     UNUSED NOW! (do repeat duplicate warnings)
+ [ref]         uses the format "[Ref.~12, given note]" (useful with 
                the superscript option)
- [nospace]     eliminates the spaces after commas in the number list.
+ [nospace]     eliminates the spaces after commas in the number list
  [space]       uses a full inter-word space after the commas
- [nosort]      prevents sorting of the numbers (default is to sort, and a
+ [nobreak]     eliminate all line-breaks
+ [nosort]      prevents sorting of the numbers (default is to sort, and the...
  [sort]        option is provided for completeness).
  [nomove]      prevents moving the superscript cite after punctuation.
  [move]        is the default
@@ -419,19 +527,19 @@ There are several options for \usepackage{cite}, some already mentioned.
  [compress]    is the default
  [biblabel]    define the bibliography label as a superscript
 
-There are several commands that you may redefine to change the formatting
-of citation lists:
+There are several commands that you may redefine (using \renewcommand
+or \def) to change the formatting of citation lists:
 
-command       function                   default
-----------    -----------------------    ----------------------------
-\citeform     reformats each number      nothing
-\citepunct    printed between numbers    comma + penalty + thin space
-\citeleft     left delimiter of list     [
-\citeright    right delimeter of list    ]
-\citemid      printed before note        comma + space
-\citedash     used in a compressed range endash + penalty
-\CiteMoveChars  charcters that move      .,:;
-\OverciteFont   font selection command for superscripts
+command          function                    default
+----------       -----------------------     ----------------------------
+\citeform        reformats each number       nothing
+\citepunct       printed between numbers     comma + penalty + thin space
+\citeleft        left delimiter of list      [
+\citeright       right delimeter of list     ]
+\citemid         printed before note         comma + penalty + space
+\citedash        used in a compressed range  endash + penalty
+\CiteMoveChars   charcters that move         .,:;
+\OverciteFont    font sel. for superscripts  \fontsize{\sf@size}...
 
 The left/mid/right commands don't affect the formatting of superscript
 citations.  You may use \renewcommand to change any of these.  Remember,
@@ -464,6 +572,19 @@ superscripts in the bibliography (at any time) you can define
 Aw, OK, for your convenience, there is the [biblabel] package option that
 just performs this definition (sort of).
 
+Line breaking can be turned off using the [nobreak] option.  It can be
+controlled more precisely by changing three numeric values, assigned 
+with \mathchardef, for controlling the line-break penalties:
+
+\citeprepenalty   penalty before cite         default \@highpenalty
+\citemidpenalty   penalty used in \citemid    default \@medpenalty
+\citepunctpenalty penalty used in \citepunct  default 1000
+
+(Use \mathchardef assignments like \mathchardef\citemidpenalty=900.
+These were chosen so as to not waste registers.)  Alternatively, the 
+commands \citemid, \citedash, and \citepunct can be redefined to use 
+different penalty parameters, or none at all.
+
 \@extra@b@citeb is a hook for other style files to further specify
 citations; for example, to number by chapter (see chapterbib.sty).
 
@@ -493,6 +614,9 @@ citations; for example, to number by chapter (see chapterbib.sty).
 % 4.0: Combine overcite with cite: [superscript] option.  Also add [nocompress]
 %      option and \CiteMoveChars; multibib hooks.
 % 4.01 \bf -> \bfseries
+% 4.02 Bury undouble action in a separate macro to avoid extra \fi error.
+% 5.0  hyperref and backref compatability! Penalty parameters and [nobreak]. 
+%      Letter prefix and suffix sorting. Stop suppressing multiple warnings.
 %
 % Send problem reports to asnd@triumf.ca