cite (3mar15)

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

4 files changed, 106 insertions, 134 deletions

diff --git a/Master/texmf-dist/doc/latex/cite/README b/Master/texmf-dist/doc/latex/cite/README
index 02ad1217160..83b82d135e9 100644
--- a/Master/texmf-dist/doc/latex/cite/README
+++ b/Master/texmf-dist/doc/latex/cite/README
@@ -15,7 +15,7 @@ and chapterbib.ltx, and already typeset pdf versions.
 
 They are all released under a very simple permissive license in
 the MIT/BSD style:  They may be freely used, transmitted, reproduced, 
-or modified provided that [the copyright and permission] notice is 
+or modified provided that the copyright and permission notice is 
 left intact.
 
 
diff --git a/Master/texmf-dist/doc/latex/cite/chapterbib.ltx b/Master/texmf-dist/doc/latex/cite/chapterbib.ltx
index d0ac5dcf98a..b134ac1b173 100644
--- a/Master/texmf-dist/doc/latex/cite/chapterbib.ltx
+++ b/Master/texmf-dist/doc/latex/cite/chapterbib.ltx
@@ -240,4 +240,4 @@ Put \cs{bibliographystyle} and \cs{bibliography} commands in
  The \cs{citepunct} command gives the punctuation (comma-penalty-space)
  between items in the \cs{cite} list, and you can redefine it.
 
-\end{document}
\ No newline at end of file
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/cite/cite.ltx b/Master/texmf-dist/doc/latex/cite/cite.ltx
index 285569ad6f4..663603c3691 100644
--- a/Master/texmf-dist/doc/latex/cite/cite.ltx
+++ b/Master/texmf-dist/doc/latex/cite/cite.ltx
@@ -2,12 +2,12 @@
 %  cite.ltx   Manual for cite.sty
 %
 %
-%  Copyright (c) 1989-2010 by Donald Arseneau
+%  Copyright (c) 1989-2015 by Donald Arseneau
 %
-%  Version date (Sep 2010)
+%  Version date (Feb 2015)
 %
 \documentclass[12pt,a4paper]{ltxdoc}
-%\overfullrule=1pt
+\overfullrule=1pt
 \addtolength{\textwidth}{1cm}
 \MakeShortVerb{\"}
 \hyphenpenalty=600
@@ -18,7 +18,7 @@
 
 \title{The cite package:\\ well formed numeric citations}
 \author{Donald Arseneau\\ asnd@triumf.ca}
-\date{2010/09/10}
+\date{2015/02/27}
 \begin{document}
 \maketitle
 
@@ -26,15 +26,15 @@
   The cite package modifies \LaTeX's normal citation mechanism for 
 improved handling of numeric citations. It provides compressed, sorted 
 lists of numerical or partly-numerical citations, as regular text or 
-superscripts.  Generally, no changes to the usage of \cs{cite} commands
-is required.
+as superscripts.  Generally, no changes to the usage of \cs{cite} commands
+in the input are required.
 \end{abstract}
 
 
 \begin{footnotesize}
-\noindent The cite package is Copyright \copyright\ 1989--2010 by 
+\noindent The cite package is Copyright \copyright\ 1989--2015 by 
 Donald Arseneau (Vancouver, Canada).\\
-The package (cite.sty) and this documentation (cite.ltx,cite.pdf) may be 
+The package (cite.sty) and this documentation (cite.ltx, cite.pdf) may be 
 freely transmitted, reproduced, or modified for any purpose provided that the
 copyright notice is left intact.
 (Small excerpts may of course be taken and used without any restriction.)
@@ -45,112 +45,58 @@ copyright notice is left intact.
 Insert "\usepackage{cite}" in the document's preamble for improved handling
 of numeric citations, behaving as follows:
 
-\snugger\paragraph*{Spacing} Put a comma and a small space between 
-  each citation number. The option [nospace] removes that space, and
+\snugger\paragraph*{Spacing}  A small space is typeset after commas 
+  in the citation list. The option [nospace] removes that space, and
   the option [space] replaces it with an ordinary inter-word space.
 
-\snugger\paragraph*{Compress groups} 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].
+\snugger\paragraph*{Sorting} Citations in a list are sorted into ascending
+  order. The [nosort] package option turns off sorting.
+  Sortable citations must be numeric or mostly-numeric (see below).
+  Non-sortable entries are printed before all sortable ones.
+
+\snugger\paragraph*{Compression} Groups of three or more consecutive numbers
+  are compressed into a range using an en-dash.  For example, the (poor) list
+  [7,5,6,?,4,9,8,Einstein,6] would display as [?,Einstein,4--6,6--9].
   Compression of ranges is disabled by the [nocompress] package option.
 
-\snugger\paragraph*{Sorting} 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:
-   \begin{enumerate}\itemsep=-\parsep
-    \item  \meta{number}
-    \item  \meta{optional-char}\meta{number}\meta{optional-char}
-    \item  \meta{number}\meta{separator-char}\meta{number}
-  \end{enumerate}
-  Forms 1 and 2 are really the same, and they mix well, but form 3 is
-  different, so it can't be mixed with the other forms (not that you 
-  would want to).
-  Non-sortable forms (those not listed) are printed before
-  all sortable forms.  Here \meta{number} means a positive integer (natural 
-  number) less than some limit (different for each form), \meta{optional-char}
-  is a single printable character (or nothing), and \meta{separator-char} 
-  is also a single printable character.
-
-\snugger\paragraph*{Prefix/suffix letters} Sort citations with prefix 
-  and/or suffix characters (form~2) such that
-  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].
+\snugger\paragraph*{Non-numbers} Sorting and compression work with (positive) 
+  numbers ("8,6,7,9" gives [6--9]) as well as numbers with prefix or suffix 
+  characters ([5a--5c] or [T1--T4]), and also dual numbers with a separator 
+  character ([1.11--1.15]). Dual numbers don't mix well with single numbers. 
+  Other forms of entry are printed before all sortable forms.  
+
+\snugger\paragraph*{Superscript} With package option [superscript] 
+  (or [super] for short), citations are displayed as superscripts,
+  except those with an optional note, which are printed on-line
+  with brackets. 
+
+  Superscript citations use \emph{the same input format} as ordinary
+  citations to produce different output. Blank space before the "\cite"
+  command is discarded, and trailing punctuation is moved to come before
+  the superscript citation. For example, `"information \cite{source};"'
+  ignores the space before "\cite" and puts the semicolon before the number
+  to give `information;$^{12}$\,', just as if you typed `"information;$^{12}$"'.
+  Doubling of periods (.., ?., !.) is checked for and suppressed.  You may 
+  disable movement with the [nomove] package option.
+
+\snugger\paragraph*{Line Breaks} Line breaks before and within the citation 
+  (after dashes, and after punctuation) are permitted, but discouraged by
+  `penalties' (given by "\citeprepenalty", "\citemidpenalty", and 
+  "\citepunctpenalty"; see Customization). The option [nobreak] prohibits 
+  these breaks. No breaks are permitted with superscript cites.
+
+\snugger\paragraph*{Space before} Regular-text citations have the preceding space
+  adjusted to be a normal inter-word space, even if there is no space in the
+  input.  The [noadjust] option disables this.  Superscript citations
+  have all preceding space removed.
 
 \snugger\paragraph*{Numbers alone}  The command "\citen" is provided to give
-  just the citation numbers without the brackets or superscript
+  just the citation number(s) without the brackets or superscript
   and other formatting.  Aliases are "\citenum" and "\citeonline" for easy
   conversion to other citation packages.
 
-\snugger\paragraph*{Breaks} Allow, but discourage, line breaks within
-  the group of citations (after dashes, and after punctuation). 
-  Penalties are "\citepunctpenalty" and "\citemidpenalty". 
 
-\snugger\paragraph*{Breaks and spaces before} Allow but strongly discourage
-  line-breaks before the entire citation, provided it is a regular text 
-  cite (not superscript) and no different penalty was specified there
-  (thus, "~\cite{X}" will not permit a line break).  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}".
-
-\snugger\paragraph*{Prohibiting breaks} All breaks can be forbidden 
-  with the [nobreak] package option.  Allowance of any type of line break can 
-  be adjusted independently by setting the parameters "\citeprepenalty", 
-  "\citemidpenalty", and "\citepunctpenalty" (see Customization below).
-
-\snugger\paragraph*{Superscript} With package option [superscript] 
-  (or [super] for short), display citation numbers as superscripts.
-  But if the citation has an optional note, it is printed on-line
-  with brackets.  Superscripted citations follow these additional rules:
-  \begin{itemize}
-   \setlength\itemsep{0pt}
-
-\item Superscript citations use \emph{the same input format} as ordinary
-   citations to produce different output. Blank space before the |\cite|
-   command is discarded, and trailing punctuation is moved to come before
-   the superscript citation. For example, `"information \cite{source};"'
-   ignores the space before "\cite" and puts the semicolon before the number
-   to give `information;$^{12}$\,', just as if you typed `"information;$^{12}$"'.
-   You may disable movement with the [nomove] package option.
-
-\item The punctuation characters that will migrate before the superscript are
-   listed in the macro "\CiteMoveChars", which you can redefine (using 
-   "\renewcommand").  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$.
-
-\item 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.S.A. \cite{space}."' and 
-   `"et al.\@ \cite{many}."' will give doubled periods.  Type `"\ "' (backslash 
-   space) after abbreviations like `et al.'  ("et al.\ \cite{many}.")
-   to get the right spacing within a sentence whether or not a citation follows,
-   and prevent double periods with the superscript cite. You could use "\@" to 
-   fix the N.S.A. example ("N.S.A\@. \cite{space}.") but that gives the wrong
-   spacing when there is no citation, so it should be inserted only where a
-   cite follows.
-
-\item Remember, these rules regarding punctuation only apply when the [super]
-   or [superscript] option was given (or overcite.sty used) and the [nomove]
-   option was \emph{not} given.
-
-\end{itemize}
-
-\section*{Customization}
+\section*{Options}
 
 There are several options for "\usepackage{cite}", some already mentioned.
 \begin{center}
@@ -162,15 +108,15 @@ There are several options for "\usepackage{cite}", some already mentioned.
  [nospace]    & eliminates the spaces after commas in the number list\\\relax
  [space]      & uses a full inter-word space after the commas\\\relax
  [nobreak]    & eliminate all line-breaks\\\relax
- [nosort]     & prevents sorting of the numbers (default is to sort, and the\dots\\\relax
- [sort]       & option is provided for completeness).\\\relax
+ [nosort]     & prevents sorting of the numbers (default is to sort, \dots\\\relax
+ [sort]       & \dots and this option is provided for completeness).\\\relax
  [nomove]     & prevents moving the superscript cite after punctuation\\\relax
- [move]       & is the default\\\relax
+ [move]       & moving punctuation is the default\\\relax
  [noadjust]   & disables `smart' handling of space before a cite\\\relax
  [adjust]     & is the default\\\relax
  [nocompress] & inhibit compression of consecutive numbers into ranges\\\relax
  [compress]   & is the default\\\relax
- [biblabel]   & define the bibliography label as a superscript
+ [biblabel]   & define the bibliography label to match "\cite"
 \end{tabular}
 \end{center}
 
@@ -178,39 +124,67 @@ If your citations are not numeric, and not of any near-numeric sortable form,
 then you should probably not use cite.sty; but if you must, then at least 
 use the [nosort,nocompress] options.
 
+
+
+\section*{More Customization}
+
+The punctuation characters that will migrate before superscript cites are
+listed in the macro "\CiteMoveChars", which you can redefine (using 
+"\renewcommand").  The default set of characters is ".,;:".  Perhaps 
+"!"~and~"?" should be included too, but they weren't listed in the
+(APS)  style manual, and they do put too much visual separation between 
+the cite and what it applies to.  Feel free to redefine "\CiteMoveChars". 
+Quote marks should be typed before the "\cite", so do not need to move.
+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$
+
+When moving punctuation before a superscript cite, the spacing after the
+citation is set according to the final punctuation mark moved, and doubling
+of periods (.., ?., !.) is checked for and suppressed. There is a problem
+with double periods after a capitalized abbreviation or directly after "\@" :
+Both of `"N.S.A. \cite{space}."' and `"et al.\@ \cite{many}."' will give
+doubled periods.  Type `"\ "' (backslash space) after abbreviations like `et
+al.'  ("et al.\ \cite{many}.")  to get the right spacing within a sentence
+whether or not a citation follows, and prevent double periods with the
+superscript cite. You could use "\@" to fix the N.S.A. example
+("N.S.A\@. \cite{space}.") but that gives the wrong spacing when there is no
+citation, so it should be inserted only where a cite follows.
+
 There are several commands that you may redefine to change the 
 formatting of citation lists:
-
 \begin{center}
 \begin{tabular}{@{}lll@{}}
 command      &    function          &          default\\
 \hline
 \cs{citeform}      &  reformats each number      & nothing\\
-\cs{citepunct}     &  printed between numbers    & comma, penalty, thin space\\
+\cs{citepunct}     &  printed between numbers    & comma, penalty, thinspace\\
 \cs{citeleft}      &  left delimiter of list     & [\\
 \cs{citeright}     &  right delimeter of list    & ]\\
 \cs{citemid}       &  printed before note        & comma, penalty, space\\
 \cs{citedash}      &  used in compressed range   & endash, penalty\\
-\cs{CiteMoveChars} &  characters that move        & \texttt{.,:;}\\
+\cs{CiteMoveChars} &  characters that get moved  & \texttt{.,:;}\\
 \cs{OverciteFont}  &  font sel. for superscripts & \relax"\fontsize{\sf@size}"\dots\\
 \end{tabular}
 \end{center}
 
-The left/mid/right commands don't affect the formatting of superscript
-citations.  You may use "\renewcommand" to change any of these.  Remember,
-these commands are extensions made by this package; they are not regular
+The left/mid/right commands apply to regular test citations, and don't affect the 
+formatting of superscript citations.  You may use "\renewcommand" to change any 
+of these.  Remember, these commands are extensions made by this package; they are not regular
 LaTeX.  Some examples of changes:
 
 \begin{flushleft}
 "\renewcommand\citeform[1]{\romannumeral 0#1}}" $\to$  roman i,vi\\
-"\renewcommand\citeform[1]{(#1)}" $\to$  parentheses (1)--(5),(9)\\
+"\renewcommand\citeform[1]{[#1]}" $\to$  individual brackets [1]--[5],[9]\\
 "\renewcommand\citeform{\thechapter.}" $\to$  by chapter: \textsuperscript{2.18--2.21}\\
 "\renewcommand\citepunct{,}" $\to$  no space and no breaks at commas\\
 "\renewcommand\citemid{; }" $\to$  semicolon before optional note\\
-"\renewcommand\citeleft{(}" $\to$  parentheses around whole\\
+"\renewcommand\citeleft{(}" $\to$  parentheses around whole list\\
 "\renewcommand\citeright{)}" $\to$  parentheses around whole list\\
 \end{flushleft}
 
+
 The appearance of the whole citation list is governed by "\@cite", (for 
 full-sized cites) and "\@citess" (for superscripts).  For more extensive changes 
 to the formatting, redefine these.  For example, to get brackets around the 
@@ -218,31 +192,29 @@ list of superscript numbers you can do:\\[2pt]
 \indent "\renewcommand\@citess[1]{\textsuperscript{[#1]}}"\\[2pt]
 (after "\makeatletter").
 
-Related Note:  The superscript option does not affect the numbering format
-of the bibliography; the "[12]" style is still the default.  To get
-superscripts in the bibliography (at any time) you can define\\[2pt]
-\indent
-   "\renewcommand\@biblabel[1]{\textsuperscript{#1}}"\\[2pt]
-Aw, OK, for your convenience, there is the [biblabel] package option that
-just performs this definition (sort of).
+The superscript option does not normally affect the numbering 
+format of the bibliography, which is controlled by the "\@biblabel" command.
+Just for convenience, the cite package now understands a  [biblabel] option
+that redefines "\@biblabel" to match the format of "\cite".
 
-Line breaking can be turned off using the [nobreak] option.  It can be
+Line breaking can be turned off using the [nobreak] option, but it can be
 controlled more precisely by changing three numeric values for the 
 line-break penalties:
 \begin{center}
 \begin{tabular}{lll}
 Command & Location  & Default \\
 \hline
-\cs{citeprepenalty} &  before entire cite  &  "\@highpenalty"\\
-\cs{citemidpenalty} &  used in "\citemid"  &  "\@medpenalty"\\
-\cs{citepunctpenalty}&  used in "\citepunct" &  1000
+\cs{citeprepenalty} &  before entire citation  &  "\@highpenalty"\\
+\cs{citemidpenalty} &  in "\citemid", before note  &  "\@medpenalty"\\
+\cs{citepunctpenalty}&  in "\citepunct" and "\citedash" &  1000
 \end{tabular}
 \end{center}
-Use "\mathchardef" to change these penalty values!  E.g., \\
+Use "\mathchardef" (!)~to change these penalty values, as in \\
 \indent "\mathchardef\citeprepenalty=9999"\\ 
-(Yes, that is obscure but I don't want to use up counters or to
-pretend they are counters.)  Alternatively, the commands "\citemid", 
-"\citedash", and "\citepunct" can be redefined to use different 
-penalty parameters, or none at all.
+(Yes, that is obscure but I don't want to use up counter registers 
+or to pretend the parameters are counters to be incremented.)  
+
+Alternatively, the commands "\citemid", "\citedash", and "\citepunct" 
+can be redefined to use different penalty parameters, or none at all.
 
 \end{document}
diff --git a/Master/texmf-dist/doc/latex/cite/cite.pdf b/Master/texmf-dist/doc/latex/cite/cite.pdf
index 4702476963f..f6ae188d330 100644
--- a/Master/texmf-dist/doc/latex/cite/cite.pdf
+++ b/Master/texmf-dist/doc/latex/cite/cite.pdf