cite update (13sep09)

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

1 files changed, 155 insertions, 72 deletions

diff --git a/Master/texmf-dist/tex/latex/cite/cite.sty b/Master/texmf-dist/tex/latex/cite/cite.sty
index 866acb07f4c..bedd4eb169e 100644
--- a/Master/texmf-dist/tex/latex/cite/cite.sty
+++ b/Master/texmf-dist/tex/latex/cite/cite.sty
@@ -1,6 +1,6 @@
 %     C I T E . S T Y
 %
-%     version 5.1  (Apr 2009)
+%     version 5.2  (Aug 2009)
 %
 %     Compressed, sorted lists of on-line or superscript numerical citations.
 %     see also drftcite.sty (And the stub overcite.sty)
@@ -24,11 +24,11 @@
 \catcode`\_ 8
 \catcode`\: 12
 
-%   Handle optional variations:
+%   Prepare for optional variations:
 %   [ verbose, nospace, space, ref, nosort, noadjust, superscript, nomove ],
 %   \citeform,\citeleft,\citeright,\citemid,\citepunct,\citedash
 %
-%   Set defaults:
+%   Set defaults first:
 
 %   [ on the left.  Option [ref] does: [Ref. 12, note]
 \providecommand\citeleft{[}
@@ -110,75 +110,112 @@
     \@warning {Citation `\@citeb' on page \thepage\space undefined}%
  %%   \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
+    \@cite@nonhyper@sanitize
     \@addto@cite@list
  \fi}
 
 \def\@nonhyper@@link [#1]#2#3#4{#4}
+\def\@cite@nonhyper@sanitize{\begingroup
+    \let\hyper@@link\@nonhyper@@link
+    \protected@xdef\@B@citeB{\csname b@\@citeb\@extra@b@citeb \endcsname}%
+  \endgroup}
+
+\def\@cite@out#1{\citeform{\csname #1\endcsname}}
 
-% Add entry to the list of citations.  This default definition sorts
-% numbers and numbers with other character tags.  There is presently
-% no other definition than this default, but features may be added later.
+% Add entry to the list of citations.  This default definition sorts pure
+% numbers as well as numbers with other single-character tags.  There 
+% is presently no other definition than this default, but features may 
+% be added later.
 %
 \def\@addto@cite@list{% 
-    \ifcat _\ifnum\z@<0\@B@citeB _\else A\fi % a positive number, put in list
-       \@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
+  \ifcat _\ifnum\z@<0\@B@citeB _\else A\fi % a positive number, put in list
+     \@addnumto@cite@list\@B@citeB
+  \else % citation is not a pure positive number, test for number+more combo
+     \@cite@combo@num
+  \fi
 }
 
-\def\@cite@out#1{\citeform{\csname #1\endcsname}}
+% With this \@cite@combo@num we delve into handling of numbers combined
+% with non-numeric tags.  The specific command name \@cite@combo@num can
+% serve as a hook for redefinition, perhaps to give simple non-sorting 
+% for anything not a pure number, or to attempt even more complicated
+% sorting, say dictionary sorting of textual citations.  The following
+% definition leads down the road of sorting mostly-numbers but with 
+% optional single-character prefix and/or suffix. 
+
+\def\@cite@combo@num{\expandafter\@cite@add@letnum\@B@citeB\delimiter}
+
+% First of many stages for sorting numbers with prefix/suffix characters.
+% Test for a leading token of category letter or other.
+%
+\def\@cite@add@letnum{%
+  \@if@printable@char{\@cite@add@letnumB}{\@cite@dump@now}%
+  }
+
+% Process first token, either a first digit or a prefix
+%
+\def\@cite@add@letnumB#1{%
+  \ifcat _\ifnum\z@<0#1_\else A\fi % a digit else prefix
+    \expandafter\@firstoftwo \else \expandafter\@secondoftwo \fi
+  {\@cite@add@letnumD {\z@}#1}{\@cite@add@letnumC {`#1}}%
+}
 
-% 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{%
+% Examine character after prefix to ensure it is a number.  First must
+% ensure it is a plain character token
+%
+\def\@cite@add@letnumC#1{\@if@printable@char%
+   {\@cite@add@letnumD{#1}}% continue with prefix (perhaps zero)
+   {\@cite@dump@now}% else abandon fancy processing
+}
+
+% Save prefix (if any) numerically in \@tempcnta, test next character for being
+% a digit, then collect main number
+%
+\def\@cite@add@letnumD#1#2{%
   \@tempcnta=#1\multiply\@tempcnta 16384 %
-  \afterassignment\@cite@add@letnumlet  \advance\@tempcnta 0#2\delimiter
+  \ifcat _\ifnum\z@<0#2_\else A\fi % at least one digit given, so continue
+    \afterassignment\@cite@add@letnumE \advance\@tempcnta #2%
+  \else \expandafter\@cite@dump@now \fi
 }
 
-% third stage for sorting values with prefix/suffix characters (gets suffix)
-\def\@cite@add@letnumlet#1#2\delimiter{%
+% Have collected number.  Now look for a single-character suffix.
+%
+\gdef\@cite@add@letnumE{%
   \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{b@\@citeb\@extra@b@citeb}\let\@citea\citepunct
+  \@if@printable@char{% a suffix given
+      \@cite@add@letnumF
+    }{% else, maybe nothing remains
+      \ifx\@let@token\delimiter % use number, and remove trailing \delimiter
+        \@citeaddcnta \expandafter\@gobble
+      \else % else abandon fancy processing
+        \expandafter\@cite@dump@now
       \fi
-    \fi
-  \fi}
+    }}
 
-% add pure numeric entry to cite list, with sorting
-\def\@addnumto@cite@list#1{%
-   \@tempcnta#1\relax
-   \multiply\@tempcnta\@cclvi
-   \@citeaddcnta}
+%  Have a complete compilation, but must ensure there is no trailing garbage
+%  (expect \delimiter as next token)
+%
+\def\@cite@add@letnumF#1#2{%
+  \ifx\delimiter#2\@empty % nothing left but \delimiter
+    \advance\@tempcnta`#1\relax \@citeaddcnta
+  \else % abandon all fancy processing
+    \expandafter\@cite@dump@now
+  \fi
+}
+
+% This is our bail-out when the citation cannot be processed as
+% [prefix]number[suffix]: it outputs the citation immediately
+% (unsorted) and consumes tokens to the \delimiter tag used as an
+% end-marker
+%
+\def\@cite@dump@now#1\delimiter{%
+  \@citea \@cite@out{b@\@citeb\@extra@b@citeb}\let\@citea\citepunct
+}
 
 % 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.)
+% somebody extends the definitions.)
 \def\@citeaddcnta{%
    \ifnum \@tempcnta>\@tempcntb % new highest, add to end (efficiently)
       \edef\@cite@list{\@cite@list 
@@ -188,7 +225,13 @@
       \edef\@cite@list{\expandafter\@sort@celt\@cite@list \@gobble.\@gobble.}%
    \fi
   }
-%
+
+% add pure numeric entry to cite list, with sorting
+\def\@addnumto@cite@list#1{%
+   \@tempcnta#1\relax
+   \multiply\@tempcnta\@cclvi
+   \@citeaddcnta}
+
 % \@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. 
@@ -341,6 +384,23 @@
  \def\@is@fil@ #1FIL#2\relax#3#4\@nil{#3}
 }
 
+% Test if next char is "printable" categories other or letter or active
+\def\@if@printable@char#1#2{%
+  \def\reserved@a{#1}%
+  \def\reserved@b{#2}%
+  \futurelet\@let@token\@test@print@char
+}
+
+\def\@test@print@char{%
+ \ifnum 
+    \ifcat\noexpand\@let@token A1\fi
+    \ifcat\noexpand\@let@token 11\fi
+    \ifcat\noexpand\@let@token \noexpand~1\fi%
+  0>\z@
+    \expandafter\reserved@a \else
+    \expandafter\reserved@b \fi
+}
+
 \let\nocitecount\relax  % in case \nocitecount was used for drftcite
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -355,23 +415,15 @@
  \mathchardef\citepunctpenalty=\@M
 }
 \DeclareOption{ref}{\def\citeleft{[Ref.\penalty\@M\ }}
-%  For no sorting, always add to end of list, but still calculate
-%  sort-order number (\@tempcnta) because it may be used for
-%  collapsing consecutive numbers.
-\DeclareOption{nosort}{%
-  \def\@citeaddcnta{%
-      \edef\@cite@list{\@cite@list 
-        \@celt{\number\@tempcnta}{\@B@citeB}{b@\@citeb\@extra@b@citeb}}%
-  }}
+%  To disable sorting [nosort], the redefinition depends on whether [nocompress]
+%  was also selected, so just set a flag first.
+\DeclareOption{nosort}{\let\@citeaddcnta\@empty}
 \DeclareOption{sort}{}% default!
+%  Likewise set flag for [nocompress]
+\DeclareOption{nocompress}{\let\@compress@cite\@empty}
+\DeclareOption{compress}{}% default
 \DeclareOption{nomove}{\def\oc@movep{\@tempa}\let\@citey\oc@movep}
 \DeclareOption{move}{}% default
-\DeclareOption{nocompress}{%
-  \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
 \DeclareOption{super}{\ExecuteOptions{superscript}}
 \DeclareOption{superscript}{%
   \DeclareRobustCommand{\cite}{%
@@ -380,7 +432,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}[2009/04/29 \space v 5.1]
+\ProvidesPackage{cite}[2009/08/29 \space v 5.2]
 \ProcessOptions
 
 \ifx\@citey\oc@movep\else % we are moving punctuation; must ensure sfcodes
@@ -391,6 +443,30 @@
   \ifnum\sfcode`\.=\@m \frenchspacing \fi
 \fi
 
+%  make redefinitions to handle [nosort] [nocompress] and their combination
+\ifx\@compress@cite\@empty
+   \ifx\@citeaddcnta\@empty
+      % [nosort,nocompress] -- short-circuit much processing
+      \def\@addto@cite@list{\@cite@dump@now\delimiter}
+   \else
+      % [sort,nocompress]
+      \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
+      }
+   \fi
+\else %  
+   \ifx\@citeaddcnta\@empty % [nosort,compress]
+     %  nosort: always add to end of list, but still calculate
+     %  sort-order number (\@tempcnta) because it may be used for
+     %  collapsing consecutive numbers.
+     \def\@citeaddcnta{%
+       \edef\@cite@list{\@cite@list 
+        \@celt{\number\@tempcnta}{\@B@citeB}{b@\@citeb\@extra@b@citeb}}%
+     }
+   \fi
+\fi
+
 %  Compatability with chapterbib (see use of \@extra@b@citeb)
 \@ifundefined{@extra@b@citeb}{\def\@extra@b@citeb{}}{}
 
@@ -404,9 +480,9 @@
 
 %  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!
+%  \@nocite so it applies to \cite, \citen, and \nocite.
 %
-\AtBeginDocument{\@ifundefined{Hy@backout}{}{
+\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
@@ -433,7 +509,8 @@
 
                    CITE.STY
 
-Modify LaTeX's normal citation mechanism to behave as follows:
+Modify LaTeX's normal citation mechanism for improved handling of numeric
+citations, behaving 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
@@ -542,6 +619,10 @@ There are several options for \usepackage{cite}, some already mentioned.
  [compress]    is the default
  [biblabel]    define the bibliography label as a superscript
 
+If your citations are not numeric, then you should probably not use 
+cite.sty, but if you must, then at least use the [nosort,nocompress] 
+options.
+
 There are several commands that you may redefine (using \renewcommand
 or \def) to change the formatting of citation lists:
 
@@ -603,6 +684,8 @@ 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).
 
+
+
 % Version 1991: Ignore spaces after commas in the parameter list. Move most of
 % \citen into \@cmpresscites for speed. Give the proper \spacefactor afterwards.
 % Version 1992: make \citepunct hold the punctuation between numbers (for ease
@@ -633,8 +716,8 @@ citations; for example, to number by chapter (see chapterbib.sty).
 % 5.0  hyperref and backref compatability! Penalty parameters and [nobreak]. 
 %      Letter prefix and suffix sorting. Stop suppressing multiple warnings.
 % 5.1  Fix a missing "b@" (disappearing named cites), fix nosort
+% 5.2  more robust treatment of non-numbers
 %
-% TODO: prevent "xy" from being sorted as "x0y"
 % TODO: other sorting, like dictionary or roman numeral
 % TODO: create special "final punct" that could be ", and " and likewise
 %       a "single punct" that could be " and "