| 1 |
% |
| 2 |
% cite.ltx Manual for cite.sty |
| 3 |
% |
| 4 |
% |
| 5 |
% Copyright (c) 1989-2015 by Donald Arseneau |
| 6 |
% |
| 7 |
% Version date (Feb 2015) |
| 8 |
% |
| 9 |
\documentclass[12pt,a4paper]{ltxdoc} |
| 10 |
\overfullrule=1pt |
| 11 |
\addtolength{\textwidth}{1cm} |
| 12 |
\MakeShortVerb{\"} |
| 13 |
\hyphenpenalty=600 |
| 14 |
\newcommand\snugger{\vspace{-7pt}} |
| 15 |
\sloppy |
| 16 |
|
| 17 |
\setlength\parskip{2pt} |
| 18 |
|
| 19 |
\title{The cite package:\\ well formed numeric citations} |
| 20 |
\author{Donald Arseneau\\ [email protected]} |
| 21 |
\date{2015/02/27} |
| 22 |
\begin{document} |
| 23 |
\maketitle |
| 24 |
|
| 25 |
\begin{abstract} |
| 26 |
The cite package modifies \LaTeX's normal citation mechanism for |
| 27 |
improved handling of numeric citations. It provides compressed, sorted |
| 28 |
lists of numerical or partly-numerical citations, as regular text or |
| 29 |
as superscripts. Generally, no changes to the usage of \cs{cite} commands |
| 30 |
in the input are required. |
| 31 |
\end{abstract} |
| 32 |
|
| 33 |
|
| 34 |
\begin{footnotesize} |
| 35 |
\noindent The cite package is Copyright \copyright\ 1989--2015 by |
| 36 |
Donald Arseneau (Vancouver, Canada).\\ |
| 37 |
The package (cite.sty) and this documentation (cite.ltx, cite.pdf) may be |
| 38 |
freely transmitted, reproduced, or modified for any purpose provided that the |
| 39 |
copyright notice is left intact. |
| 40 |
(Small excerpts may of course be taken and used without any restriction.) |
| 41 |
\par |
| 42 |
\end{footnotesize} |
| 43 |
|
| 44 |
\section*{Normal Use} |
| 45 |
Insert "\usepackage{cite}" in the document's preamble for improved handling |
| 46 |
of numeric citations, behaving as follows: |
| 47 |
|
| 48 |
\snugger\paragraph*{Spacing} A small space is typeset after commas |
| 49 |
in the citation list. The option [nospace] removes that space, and |
| 50 |
the option [space] replaces it with an ordinary inter-word space. |
| 51 |
|
| 52 |
\snugger\paragraph*{Sorting} Citations in a list are sorted into ascending |
| 53 |
order. The [nosort] package option turns off sorting. |
| 54 |
Sortable citations must be numeric or mostly-numeric (see below). |
| 55 |
Non-sortable entries are printed before all sortable ones. |
| 56 |
|
| 57 |
\snugger\paragraph*{Compression} Groups of three or more consecutive numbers |
| 58 |
are compressed into a range using an en-dash. For example, the (poor) list |
| 59 |
[7,5,6,?,4,9,8,Einstein,6] would display as [?,Einstein,4--6,6--9]. |
| 60 |
Compression of ranges is disabled by the [nocompress] package option. |
| 61 |
|
| 62 |
\snugger\paragraph*{Non-numbers} Sorting and compression work with (positive) |
| 63 |
numbers ("8,6,7,9" gives [6--9]) as well as numbers with prefix or suffix |
| 64 |
characters ([5a--5c] or [T1--T4]), and also dual numbers with a separator |
| 65 |
character ([1.11--1.15]). Dual numbers don't mix well with single numbers. |
| 66 |
Other forms of entry are printed before all sortable forms. |
| 67 |
|
| 68 |
\snugger\paragraph*{Superscript} With package option [superscript] |
| 69 |
(or [super] for short), citations are displayed as superscripts, |
| 70 |
except those with an optional note, which are printed on-line |
| 71 |
with brackets. |
| 72 |
|
| 73 |
Superscript citations use \emph{the same input format} as ordinary |
| 74 |
citations to produce different output. Blank space before the "\cite" |
| 75 |
command is discarded, and trailing punctuation is moved to come before |
| 76 |
the superscript citation. For example, `"information \cite{source};"' |
| 77 |
ignores the space before "\cite" and puts the semicolon before the number |
| 78 |
to give `information;$^{12}$\,', just as if you typed `"information;$^{12}$"'. |
| 79 |
Doubling of periods (.., ?., !.) is checked for and suppressed. You may |
| 80 |
disable movement with the [nomove] package option. |
| 81 |
|
| 82 |
\snugger\paragraph*{Line Breaks} Line breaks before and within the citation |
| 83 |
(after dashes, and after punctuation) are permitted, but discouraged by |
| 84 |
`penalties' (given by "\citeprepenalty", "\citemidpenalty", and |
| 85 |
"\citepunctpenalty"; see Customization). The option [nobreak] prohibits |
| 86 |
these breaks. No breaks are permitted with superscript cites. |
| 87 |
|
| 88 |
\snugger\paragraph*{Space before} Regular-text citations have the preceding space |
| 89 |
adjusted to be a normal inter-word space, even if there is no space in the |
| 90 |
input. The [noadjust] option disables this. Superscript citations |
| 91 |
have all preceding space removed. |
| 92 |
|
| 93 |
\snugger\paragraph*{Numbers alone} The command "\citen" is provided to give |
| 94 |
just the citation number(s) without the brackets or superscript |
| 95 |
and other formatting. Aliases are "\citenum" and "\citeonline" for easy |
| 96 |
conversion to other citation packages. |
| 97 |
|
| 98 |
|
| 99 |
\section*{Options} |
| 100 |
|
| 101 |
There are several options for "\usepackage{cite}", some already mentioned. |
| 102 |
\begin{center} |
| 103 |
\begin{tabular}{lp{0.75\linewidth}} |
| 104 |
[superscript]& use superscripts for cites without optional notes\\\relax |
| 105 |
[super] & alias for [superscript] (like natbib)\\\relax |
| 106 |
[ref] & uses the format "[Ref.~12, given note]" (useful with |
| 107 |
the superscript option)\\\relax |
| 108 |
[nospace] & eliminates the spaces after commas in the number list\\\relax |
| 109 |
[space] & uses a full inter-word space after the commas\\\relax |
| 110 |
[nobreak] & eliminate all line-breaks\\\relax |
| 111 |
[nosort] & prevents sorting of the numbers (default is to sort, \dots\\\relax |
| 112 |
[sort] & \dots and this option is provided for completeness).\\\relax |
| 113 |
[nomove] & prevents moving the superscript cite after punctuation\\\relax |
| 114 |
[move] & moving punctuation is the default\\\relax |
| 115 |
[noadjust] & disables `smart' handling of space before a cite\\\relax |
| 116 |
[adjust] & is the default\\\relax |
| 117 |
[nocompress] & inhibit compression of consecutive numbers into ranges\\\relax |
| 118 |
[compress] & is the default\\\relax |
| 119 |
[biblabel] & define the bibliography label to match "\cite" |
| 120 |
\end{tabular} |
| 121 |
\end{center} |
| 122 |
|
| 123 |
If your citations are not numeric, and not of any near-numeric sortable form, |
| 124 |
then you should probably not use cite.sty; but if you must, then at least |
| 125 |
use the [nosort,nocompress] options. |
| 126 |
|
| 127 |
|
| 128 |
|
| 129 |
\section*{More Customization} |
| 130 |
|
| 131 |
The punctuation characters that will migrate before superscript cites are |
| 132 |
listed in the macro "\CiteMoveChars", which you can redefine (using |
| 133 |
"\renewcommand"). The default set of characters is ".,;:". Perhaps |
| 134 |
"!"~and~"?" should be included too, but they weren't listed in the |
| 135 |
(APS) style manual, and they do put too much visual separation between |
| 136 |
the cite and what it applies to. Feel free to redefine "\CiteMoveChars". |
| 137 |
Quote marks should be typed before the "\cite", so do not need to move. |
| 138 |
This gives one difficulty~-- punctuation following quotes won't migrate |
| 139 |
inside the quotation: e.g., "``Transition State Theory''\cite{Eyring}." |
| 140 |
gives out ``Transition State Theory''.$^8$, but you may want the period |
| 141 |
inside the quotes, thus: ``Transition State Theory.''$^8$ |
| 142 |
|
| 143 |
When moving punctuation before a superscript cite, the spacing after the |
| 144 |
citation is set according to the final punctuation mark moved, and doubling |
| 145 |
of periods (.., ?., !.) is checked for and suppressed. There is a problem |
| 146 |
with double periods after a capitalized abbreviation or directly after "\@" : |
| 147 |
Both of `"N.S.A. \cite{space}."' and `"et al.\@ \cite{many}."' will give |
| 148 |
doubled periods. Type `"\ "' (backslash space) after abbreviations like `et |
| 149 |
al.' ("et al.\ \cite{many}.") to get the right spacing within a sentence |
| 150 |
whether or not a citation follows, and prevent double periods with the |
| 151 |
superscript cite. You could use "\@" to fix the N.S.A. example |
| 152 |
("N.S.A\@. \cite{space}.") but that gives the wrong spacing when there is no |
| 153 |
citation, so it should be inserted only where a cite follows. |
| 154 |
|
| 155 |
There are several commands that you may redefine to change the |
| 156 |
formatting of citation lists: |
| 157 |
\begin{center} |
| 158 |
\begin{tabular}{@{}lll@{}} |
| 159 |
command & function & default\\ |
| 160 |
\hline |
| 161 |
\cs{citeform} & reformats each number & nothing\\ |
| 162 |
\cs{citepunct} & printed between numbers & comma, penalty, thinspace\\ |
| 163 |
\cs{citeleft} & left delimiter of list & [\\ |
| 164 |
\cs{citeright} & right delimeter of list & ]\\ |
| 165 |
\cs{citemid} & printed before note & comma, penalty, space\\ |
| 166 |
\cs{citedash} & used in compressed range & endash, penalty\\ |
| 167 |
\cs{CiteMoveChars} & characters that get moved & \texttt{.,:;}\\ |
| 168 |
\cs{OverciteFont} & font sel. for superscripts & \relax"\fontsize{\sf@size}"\dots\\ |
| 169 |
\end{tabular} |
| 170 |
\end{center} |
| 171 |
|
| 172 |
The left/mid/right commands apply to regular test citations, and don't affect the |
| 173 |
formatting of superscript citations. You may use "\renewcommand" to change any |
| 174 |
of these. Remember, these commands are extensions made by this package; they are not regular |
| 175 |
LaTeX. Some examples of changes: |
| 176 |
|
| 177 |
\begin{flushleft} |
| 178 |
"\renewcommand\citeform[1]{\romannumeral 0#1}}" $\to$ roman i,vi\\ |
| 179 |
"\renewcommand\citeform[1]{[#1]}" $\to$ individual brackets [1]--[5],[9]\\ |
| 180 |
"\renewcommand\citeform{\thechapter.}" $\to$ by chapter: \textsuperscript{2.18--2.21}\\ |
| 181 |
"\renewcommand\citepunct{,}" $\to$ no space and no breaks at commas\\ |
| 182 |
"\renewcommand\citemid{; }" $\to$ semicolon before optional note\\ |
| 183 |
"\renewcommand\citeleft{(}" $\to$ parentheses around whole list\\ |
| 184 |
"\renewcommand\citeright{)}" $\to$ parentheses around whole list\\ |
| 185 |
\end{flushleft} |
| 186 |
|
| 187 |
|
| 188 |
The appearance of the whole citation list is governed by "\@cite", (for |
| 189 |
full-sized cites) and "\@citess" (for superscripts). For more extensive changes |
| 190 |
to the formatting, redefine these. For example, to get brackets around the |
| 191 |
list of superscript numbers you can do:\\[2pt] |
| 192 |
\indent "\renewcommand\@citess[1]{\textsuperscript{[#1]}}"\\[2pt] |
| 193 |
(after "\makeatletter"). |
| 194 |
|
| 195 |
The superscript option does not normally affect the numbering |
| 196 |
format of the bibliography, which is controlled by the "\@biblabel" command. |
| 197 |
Just for convenience, the cite package now understands a [biblabel] option |
| 198 |
that redefines "\@biblabel" to match the format of "\cite". |
| 199 |
|
| 200 |
Line breaking can be turned off using the [nobreak] option, but it can be |
| 201 |
controlled more precisely by changing three numeric values for the |
| 202 |
line-break penalties: |
| 203 |
\begin{center} |
| 204 |
\begin{tabular}{lll} |
| 205 |
Command & Location & Default \\ |
| 206 |
\hline |
| 207 |
\cs{citeprepenalty} & before entire citation & "\@highpenalty"\\ |
| 208 |
\cs{citemidpenalty} & in "\citemid", before note & "\@medpenalty"\\ |
| 209 |
\cs{citepunctpenalty}& in "\citepunct" and "\citedash" & 1000 |
| 210 |
\end{tabular} |
| 211 |
\end{center} |
| 212 |
Use "\mathchardef" (!)~to change these penalty values, as in \\ |
| 213 |
\indent "\mathchardef\citeprepenalty=9999"\\ |
| 214 |
(Yes, that is obscure but I don't want to use up counter registers |
| 215 |
or to pretend the parameters are counters to be incremented.) |
| 216 |
|
| 217 |
Alternatively, the commands "\citemid", "\citedash", and "\citepunct" |
| 218 |
can be redefined to use different penalty parameters, or none at all. |
| 219 |
|
| 220 |
\end{document} |