From 8ac4866fb38af45e87b21dff99b0d56b506721a6 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 13 Sep 2010 19:16:35 +0000
Subject: cite update (12sep10)

git-svn-id: svn://tug.org/texlive/trunk@19710 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/tex/latex/cite/cite.sty | 178 ++++++++++++++++++------------
 1 file changed, 109 insertions(+), 69 deletions(-)

(limited to 'Master/texmf-dist/tex/latex/cite/cite.sty')

diff --git a/Master/texmf-dist/tex/latex/cite/cite.sty b/Master/texmf-dist/tex/latex/cite/cite.sty
index bedd4eb169e..e8187781788 100644
--- a/Master/texmf-dist/tex/latex/cite/cite.sty
+++ b/Master/texmf-dist/tex/latex/cite/cite.sty
@@ -1,11 +1,11 @@
 %     C I T E . S T Y
 %
-%     version 5.2  (Aug 2009)
+%     version 5.3  (Sep 2010)
 %
 %     Compressed, sorted lists of on-line or superscript numerical citations.
 %     see also drftcite.sty (And the stub overcite.sty)
 %
-%     Copyright (C) 1989-2009 by Donald Arseneau
+%     Copyright (C) 1989-2010 by Donald Arseneau
 %     These macros may be freely used, transmitted, reproduced, or modified
 %     provided that this notice is left intact.
 %
@@ -128,11 +128,9 @@
 % 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 pure positive number, test for number+more combo
-     \@cite@combo@num
-  \fi
+ \@cite@posnumtest\@B@citeB
+   {\@addnumto@cite@list\@B@citeB}%  a positive number, put in list
+   {\@cite@combo@num}% not a pure positive number, test for combo forms
 }
 
 % With this \@cite@combo@num we delve into handling of numbers combined
@@ -143,21 +141,22 @@
 % 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}
+\def\@cite@combo@num{\expandafter\@cite@try@combo\@B@citeB\delimiter}
 
 % First of many stages for sorting numbers with prefix/suffix characters.
-% Test for a leading token of category letter or other.
+% Test for a leading token of category letter or other (appropriate for
+% all combination types).
 %
-\def\@cite@add@letnum{%
-  \@if@printable@char{\@cite@add@letnumB}{\@cite@dump@now}%
-  }
+\def\@cite@try@combo{%
+  \@if@printable@char{\@cite@try@prefix}{\@cite@gobbledump@now}}
 
+% First token is good, so test for a character prefix before a number.
 % 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}}%
+\def\@cite@try@prefix#1{% #1 is first character of citation
+  \@cite@posnumtest{#1}% a digit else prefix
+   {\@cite@add@letnumD {\z@}#1}% no prefix character (use zero)
+   {\@cite@add@letnumC {`#1}}% prefix char; use the char code
 }
 
 % Examine character after prefix to ensure it is a number.  First must
@@ -165,52 +164,70 @@
 %
 \def\@cite@add@letnumC#1{\@if@printable@char%
    {\@cite@add@letnumD{#1}}% continue with prefix (perhaps zero)
-   {\@cite@dump@now}% else abandon fancy processing
+   {\@cite@gobbledump@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{%
+\def\@cite@add@letnumD#1#2{% #1 = numeric code for prefix, #2 = next char
   \@tempcnta=#1\multiply\@tempcnta 16384 %
-  \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
+  \@cite@posnumtest{#2}% if next char is a digit, continue with number:
+   {\afterassignment\@cite@add@letnumE \advance\@tempcnta #2}%
+   {\@cite@gobbledump@now}% No number so output citation
 }
 
-% Have collected number.  Now look for a single-character suffix.
+% Have collected number.  Now look for a non-number suffix or separator.
 %
 \gdef\@cite@add@letnumE{%
   \multiply\@tempcnta\@cclvi
-  \@if@printable@char{% a suffix given
+  \@if@printable@char{% a suffix or separator 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
+      \else % non-printable char found, so abandon fancy processing
+        \expandafter\@cite@gobbledump@now
       \fi
     }}
 
-%  Have a complete compilation, but must ensure there is no trailing garbage
-%  (expect \delimiter as next token)
+%  Have everything up to a suffix or separator character.  Check 
+%  following to see which. Three possibilites are (1) noting =>
+%  a suffix; (2) number => separator-number; (3) other => garbage.
 %
-\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
-}
+\def\@cite@add@letnumF#1#2\delimiter{% #1 = suffix/separator #2=rest
+  \advance\@tempcnta`#1\relax
+  \@cite@posnumtest{#2}{\@cite@add@numsepnum{#2}}% handle as num sep num
+    {% else...
+     \ifx\delimiter#2\delimiter % nothing left, so #1 is a suffix
+       \@citeaddcnta
+     \else % some non-number; dump it
+       \@cite@dump@now
+     \fi
+}}
+
+% Handle citation as number separator number.
+% Yes, there is a bug that the list 1.1,1.258,1.515 will be compressed as
+% 1.1-1.515; so sue me.
+
+\def\@cite@add@numsepnum#1{% #1 = last number
+  \ifnum\@tempcnta<262144 % OK numeric range
+    \multiply\@tempcnta 4096
+    \advance\@tempcnta #1 % num,sep,num have maximum numbers:  1023, 255, 4095
+    \@citeaddcnta
+  \else % out of range, treat as raw string
+    \@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
+% [prefix]number[suffix] or number[sep]number: 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
-}
+\def\@cite@gobbledump@now#1\delimiter{\@cite@dump@now}%
+
+\def\@cite@dump@now{%
+  \@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 
@@ -384,13 +401,17 @@
  \def\@is@fil@ #1FIL#2\relax#3#4\@nil{#3}
 }
 
-% Test if next char is "printable" categories other or letter or active
+% Test if next token is a char of "printable" categories other or letter or 
+% active.  Syntax:
+%  \@if@printable@char {do if printable}{do if not printable}<char>
+%
 \def\@if@printable@char#1#2{%
   \def\reserved@a{#1}%
   \def\reserved@b{#2}%
   \futurelet\@let@token\@test@print@char
 }
 
+% Note side-effect of redefining \reserved@a and \reserved@b
 \def\@test@print@char{%
  \ifnum 
     \ifcat\noexpand\@let@token A1\fi
@@ -401,6 +422,12 @@
     \expandafter\reserved@b \fi
 }
 
+% Test for a pure positive number: {possible number}{true}{false}
+\def\@cite@posnumtest#1{%
+  \ifcat _\ifnum\z@<0#1_\else A\fi
+    \expandafter\@firstoftwo \else \expandafter\@secondoftwo \fi
+}
+
 \let\nocitecount\relax  % in case \nocitecount was used for drftcite
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -432,7 +459,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/08/29 \space v 5.2]
+\ProvidesPackage{cite}[2010/09/10 \space v 5.3]
 \ProcessOptions
 
 \ifx\@citey\oc@movep\else % we are moving punctuation; must ensure sfcodes
@@ -447,7 +474,7 @@
 \ifx\@compress@cite\@empty
    \ifx\@citeaddcnta\@empty
       % [nosort,nocompress] -- short-circuit much processing
-      \def\@addto@cite@list{\@cite@dump@now\delimiter}
+      \def\@addto@cite@list{\@cite@dump@now}
    \else
       % [sort,nocompress]
       \def\@compress@cite#1#2#3{%  % This is executed for each number
@@ -467,7 +494,7 @@
    \fi
 \fi
 
-%  Compatability with chapterbib (see use of \@extra@b@citeb)
+%  Compatability with chapterbib (see use of \@extra@b@citeb above and in chapterbib)
 \@ifundefined{@extra@b@citeb}{\def\@extra@b@citeb{}}{}
 
 %  Compatability with multibib (see use of \@newciteauxhandle) (Yes, this is
@@ -516,19 +543,30 @@ 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
   an ordinary inter-word space.
 
-o Sort citation numbers into ascending order, printing non-numbers before 
-  numbers.  All numbers should be greater than zero.  The [nosort] package 
-  option turns off sorting.
-
 o Compress lists of three or more consecutive numbers to one number range
   which can be split, with difficulty, after the dash.  All numbers should
   be greater than zero.  E.g., if you used to get the (nonsense) list 
   [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 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 Sort citations into ascending order (this is the default, but may also
+  be declared with the package option [sort]). The [nosort] package option
+  turns off sorting.  Sortable citations must fit one of these forms:
+    1.  <number>
+    2.  <optional-char><number><optional-char>
+    3.  <number><separator-char><number>
+  Forms 1 and 2 are really the same, and they mix well, but form 3 is
+  separate and if used simultaneously with form 1 the citations become,
+  ummm, mixed.  Non-sortable forms (those not listed) are printed before
+  all sortable forms.  Here <number> means a positive integer (natural 
+  number) less than some limit (different for each form), <optional-char>
+  is a single printable character (or nothing), and <separator-char> is also
+  a single printable character.
+
+o Sorting of citations with prefix and/or suffix characters is done so so 
+  different prefixes are grouped separately, and suffixes form sub-lists 
+  for the same number.  Compression knows about suffixes, so you can get
+  lists like [18a-18c,19] or [A2,Q1,Q3-Q5].
 
 o Allow, but discourage, line breaks within the group of citations (after
   dashes, and after punctuation). Penalties are \citepunctpenalty and
@@ -544,7 +582,7 @@ 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.)
+  obscure but I don't want to use up counters or 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
@@ -559,17 +597,18 @@ o With package option [superscript] (or [super] for short), display citation
    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$.
+   listed in the macro \CiteMoveChars, which you can redefine.  The default 
+   set of characters is ".,;:";  Perhaps ! and ? should be included too, but
+   they weren't listed in the APS style manual I looked at, and I agree with 
+   that design 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 what is quoted (when citing a quotation). This gives one
+   difficulty -- punctuation following quotes won't migrate inside the 
+   quotation: e.g., "``Transition State Theory''\cite{Eyring}." gives out
+   ``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.
@@ -577,7 +616,7 @@ o With package option [superscript] (or [super] for short), display citation
    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
+   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.
 
@@ -681,8 +720,6 @@ 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).
 
 
 
@@ -713,10 +750,13 @@ citations; for example, to number by chapter (see chapterbib.sty).
 %      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]. 
+% 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
+% 5.2  More robust treatment of non-numbers
+% 5.3  Handle sort/compress of compound citation numbers (number by chapter)
+%      such as 3.18 or 5-3.  Note that these compounds cannot have prefix or
+%      suffix letters (not enough bits in the maximum TeX number).
 %
 % TODO: other sorting, like dictionary or roman numeral
 % TODO: create special "final punct" that could be ", and " and likewise
@@ -725,4 +765,4 @@ citations; for example, to number by chapter (see chapterbib.sty).
 % Send problem reports to asnd@triumf.ca
 
 Test file integrity:  ASCII 32-57, 58-126:  !"#$%&'()*+,-./0123456789
-:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
+:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
\ No newline at end of file
-- 
cgit v1.2.3

