Debian Codegraph @

texmf-dist/doc/latex/cite/cite.ltx

raw
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}