Debian Codegraph @

texmf-dist/source/latex/revtex4/textcase.dtx

raw
1 % \iffalse
2 %% Source File: textcase.dtx
3 %% Copyright 1997 1998 David Carlisle
4 %%
5 %% This file may be distributed under the terms of the LPPL.
6 %% See 00readme.txt for details.
7 %
8 %<*dtx>
9 \ProvidesFile{textcase.dtx}
10 %</dtx>
11 %<package>\NeedsTeXFormat{LaTeX2e}
12 %<package>\ProvidesPackage{textcase}
13 %<driver> \ProvidesFile{textcase.drv}
14 % \fi
15 % \ProvidesFile{textcase.dtx}
16 [1998/11/12 v0.06 Text only upper/lower case changing (DPC)]
17 %
18 % \iffalse
19 %<*driver>
20 \documentclass{ltxdoc}
21 \usepackage{textcase}
22 \begin{document}
23 \DocInput{textcase.dtx}
24 \end{document}
25 %</driver>
26 % \fi
27 %
28 % \GetFileInfo{textcase.dtx}
29 %
30 % \changes{v0.01}{1997/09/28}
31 % {Posted to c.t.t}
32 % \changes{v0.02}{1997/09/28}
33 % {Support \cs{ensuremath}}
34 % \changes{v0.03}{1997/12/12}
35 % {Donald Arseneau: support \cs{ref} \cs{cite} \cs{label}}
36 % \changes{v0.04}{1997/12/14}
37 % {Convert to dtx form, add \cs{NoCaseChange}}
38 % \changes{v0.04}{1997/12/14}
39 % {Support (most uses of) optional argument of \cs{cite}}
40 % \changes{v0.05}{1997/12/16}
41 % {More comments from Donald,
42 % perhaps I should just give him this package for Christmas}
43 % \changes{v0.06}{1998/11/12}
44 % {overload option}
45 %
46 %
47 % \title{The \textsf{textcase} package\thanks{This file
48 % has version number \fileversion, last
49 % revised \filedate.}}
50 % \author{David Carlisle\thanks{%^^A
51 % Reorganisation to suppport skipping a wider class of
52 % things than just math done by Donald Arseneau}}
53 %
54 % \date{\filedate}
55 %
56 % \maketitle
57 %
58 % \section{Introduction}\label{intro}
59 % |\MakeTextUppercase| and |\MakeTextLowercase| are versions of the
60 % standard |\MakeUppercase| and |\MakeLowercase| that do not change
61 % the case of any math sections in their arguments.
62 %\begin{verbatim}
63 % \MakeTextUppercase{abc\ae\ \( a = b \) and $\alpha \neq a$
64 % or even \ensuremath{x=y} and $\ensuremath{x=y}$}
65 %\end{verbatim}
66 % Should produce:
67 % \begin{quotation}
68 % ABC\AE\ \( a = b \) AND $\alpha \neq a$
69 % OR EVEN \ensuremath{x=y} AND $\ensuremath{x=y}$
70 % \end{quotation}
71 %
72 % Version 0.03 of this package incorporates some changes suggested by
73 % Donald Arseneau so that as well as math mode, the arguments of
74 % |\cite|, |\label| and |\ref| are also prevented from being uppercased.
75 % So you can now go
76 %\begin{verbatim}
77 % \MakeTextUppercase{%
78 % Text in section~\ref{intro}, about \cite[pp 2--4]{bbb}}
79 %\end{verbatim}
80 % which produces
81 % \begin{quotation}
82 % \MakeTextUppercase{%
83 % Text in section~\ref{intro}, about \cite[pp 2--4]{bbb}}
84 % \end{quotation}
85 % If, instead, the standard |\MakeUppercase| were used here, the keys
86 % `into' and `bbb' would be uppercased and generate errors about
87 % undefined references to INTRO and BBB.
88 %
89 % Sometimes there may be a special section of text that should not be
90 % uppercased. This can be marked with |\NoCaseChange|, as follows.
91 %\begin{verbatim}
92 % \MakeTextUppercase{%
93 % Text \NoCaseChange{More Text} yet more text}
94 %\end{verbatim}
95 % which produces
96 % \begin{quotation}
97 % \MakeTextUppercase{%
98 % Text \NoCaseChange{More Text} yet more text}
99 % \end{quotation}
100 %
101 % |\NoCaseChange| has other uses. If for some reason you need a
102 % tabular environment within an uppercased section, then you need
103 % to ensure that the name `tabular' and the preamble (eg `ll')
104 % does not get uppercased:
105 %\begin{verbatim}
106 % \MakeTextUppercase{%
107 % Text \NoCaseChange{\begin{tabular}{ll}}%
108 % table&stuff\\goes&here
109 % \NoCaseChange{\end{tabular}}
110 % More text}
111 %\end{verbatim}
112 % which produces
113 % \begin{quotation}
114 % \MakeTextUppercase{%
115 % Text \NoCaseChange{\begin{tabular}{ll}}%^^A
116 % table&stuff\\goes&here
117 % \NoCaseChange{\end{tabular}}
118 % More text}
119 % \end{quotation}
120 %
121 % \section{Features and Foibles}
122 %
123 % \subsection{Nested text}
124 % The commands defined here only skip math sections and |\ref| arguments
125 % if they are not `hidden' inside a |{ }| brace group. All text inside
126 % such a group will be made uppercase just as with the standard
127 % |\MakeUppercase|.
128 %\begin{verbatim}
129 % \MakeTextUppercase{a b {c $d$} $e$}
130 %\end{verbatim}
131 % produces
132 % \begin{quotation}
133 % \MakeTextUppercase{a b {c $d$} $e$}
134 % \end{quotation}
135 % Of course, this restriction does not apply to the arguments of the
136 % supported commands |\ensuremath|, |\label|, |\ref|, and |\cite|.
137 %
138 % If you cannot arrange for your
139 % mathematics to be at the outer level of brace grouping, you should
140 % use the following basic technique (which works even with the standard
141 % |\MakeUppercase| command). Define a new command that expands to your
142 % math expression, and then use that command, with |\protect|, in the
143 % text to be uppercased. Note that if the text being uppercased is in a
144 % section title or other moving argument you may need to make the
145 % definition in the document preamble, rather than just before the
146 % section command, so that the command is defined when the table of
147 % contents file is read.
148 %\begin{verbatim}
149 % \MakeTextUppercase{%
150 % Text \fbox{$a=b$ and $x=y$}}%
151 %
152 % \newcommand{\mathexprone}{$a=b$}
153 % \newcommand{\mathexprtwo}{$x=y$}
154 % \MakeTextUppercase{%
155 % Text \fbox{\protect\mathexprone\ and \protect\mathexprtwo}}%
156 %\end{verbatim}
157 % which produces
158 % \begin{quotation}
159 % \MakeTextUppercase{%
160 % Text \fbox{$a=b$ and $x=y$}}%
161 %
162 % \newcommand{\mathexprone}{$a=b$}
163 % \newcommand{\mathexprtwo}{$x=y$}
164 % \MakeTextUppercase{%
165 % Text \fbox{\protect\mathexprone\ and \protect\mathexprtwo}}%
166 % \end{quotation}
167 %
168 % \subsection{Citations}
169 % As documented above, |\cite| and |\ref| commands are not uppercased by
170 % |\MakeTextUppercase|. If you are using a non-numeric citation scheme
171 % you may want the replacement text for |\cite| to be uppercased.
172 %
173 % It is difficult to arrange that |\MakeTextUppercase| uppercases such
174 % text, not least because this would lead to interaction with the many
175 % bibliography packages which redefine |\cite| one way or another. One
176 % possibility to achieve this is to use Donald Arseneau's cite package
177 % and to locally redefine |\citeform| to add |\MakeUppercase| around
178 % the final text string produced by |\cite|.
179 %\begin{verbatim}
180 % \MakeTextUppercase{%
181 % Text \cite{bbb} and \cite{ccc}}
182 %
183 % {\renewcommand\citeform{\MakeUppercase}\MakeTextUppercase{%
184 % Text \cite{bbb} and \cite{ccc}}}
185 %\end{verbatim}
186 % which produces\footnote{This is faked, so this document does not
187 % rely on \texttt{cite.sty} being installed}
188 % \begin{quotation}
189 % TEXT [1] AND [David Carlisle 1997]
190 %
191 % TEXT [1] AND [DAVID CARLISLE 1997]
192 % \end{quotation}
193 %
194 % \subsection{overload Option}
195 % By default the package only defines new commands, |\MakeTextUppercase|
196 % and |\MakeTextlowercase| as described above. You may wish to redefine
197 % the standard |\MakeUppercase| and |\MakeLowercase| commands to be
198 % the same as these new commands. So that for example headings in the
199 % book class have this new feature without any further redefinition.
200 % You may use the package option |[overload]| in which case these
201 % new definitions will be overloaded on to the existing command names.
202 %
203 % \begin{thebibliography}{9}
204 %
205 % \bibitem{bbb} Something numeric
206 % \bibitem[David Carlisle 1997]{ccc} Something textual
207 % \end{thebibliography}
208 %
209 % \StopEventually{}
210 %
211 % \section{Implementation}
212 %
213 % \begin{macrocode}
214 %<*package>
215 % \end{macrocode}
216 %
217 % \begin{macro}{\@uclcnotmath}
218 % This is the main macro of this package. It is basically
219 % a copy of |\MakeTextUppercase| and |\MakeTextLowercase|
220 % from the \LaTeX\ kernel, modified slightly so that they
221 % can share code (that modification could be done to the
222 % standard versions as well) and then further changed to
223 % skip certain features like math mode and |\label| arguments.
224 %
225 % The arguments are:\\
226 % |#1|: Extra commands to apply for case changing.
227 % Used to locally redefine |\i| and |\j| for uppercasing.\\
228 % |#2|: Either |##1##2| or |##2##1| to control the order
229 % in which |\let| is applied to the pairs of control
230 % sequences in |\@uclclist|.\\
231 % |#3|: |\uppercase| or |\lowercase|.\\
232 % |#4|: The text to be upper (or lower) cased.
233 % \begin{macrocode}
234 \def\@uclcnotmath#1#2#3#4{\begingroup
235 % \end{macrocode}
236 % Run extra commands (currently just to redefine |\i| and |\j|).
237 % \begin{macrocode}
238 #1%
239 % \end{macrocode}
240 %
241 % Locally set |\( \)| to be just |$ $|, so that the math skipping
242 % code can be simplified, just to look for |$|.
243 % \begin{macrocode}
244 \def\({$}\let\)\(%
245 % \end{macrocode}
246 %
247 % Set up the `non-math' things that also have to be skipped.
248 % \begin{macrocode}
249 \def\NoCaseChange##1{\noexpand\NoCaseChange{\noexpand##1}}%
250 \@nonchangecase\label
251 \@nonchangecase\ref
252 \@nonchangecase\ensuremath
253 % \end{macrocode}
254 %
255 % |\cite| a bit trickier, as we want to uppercase any optional argument.
256 % This will fail if the optional argument contains a brace group, but
257 % should catch most cases.
258 %
259 % |text \cite[page 1]{foo} more text| ends up as
260 %\begin{verbatim}
261 % \uppercase{text \toks@{\cite[page1]}%
262 % \the\toks@{foo}%
263 % \uppercase{ more text}
264 %\end{verbatim}
265 % \begin{macrocode}
266 \def\cite##1##{\toks@{\noexpand\cite##1}\@citex}%
267 \def\@citex##1{\NoCaseChange{\the\toks@{##1}}}%
268 % \end{macrocode}
269 % (|\@citex| is a scratch macro here, not a redefinition of the existing
270 % |\@citex|.)
271 %
272 % The following is essentially taken from |\MakeUppercase|.
273 % Recursively execute |\reserved@a| to |\let| the pairs in |\@uclclist|.
274 % The strange construction with |\@gobble| at the end just gobbles the
275 % final recursive call.
276 %
277 % Incidentally, packages should not use the |\reserved@|\ldots\ scratch
278 % macros, which are `reserved' for use within the \LaTeX\ kernel, but
279 % (a) this code is essentially a copy from the kernel, and
280 % (b) I'm allowed to break the rules, so there.
281 % \begin{macrocode}
282 \def\reserved@a##1##2{\let#2\reserved@a}%
283 \expandafter\reserved@a\@uclclist\reserved@b{\reserved@b\@gobble}%
284 % \end{macrocode}
285 %
286 % Expand everything first so that the `skipping' code can see what to
287 % skip and so that tokens are revealed to |\uppercase|.
288 % This makes the argument `moving'.
289 % The |$\valign$| is just a fake math expression used to terminate
290 % the parsing done by |\@skipmath|.
291 % \begin{macrocode}
292 \protected@edef\reserved@a{\endgroup
293 \noexpand\@skipmath#3#4$\valign$}%
294 % \end{macrocode}
295 %
296 % \begin{macrocode}
297 \reserved@a}
298 % \end{macrocode}
299 % \end{macro}
300 %
301 % \begin{macro}{\@nonchangecase}
302 % \begin{macrocode}
303 \def\@nonchangecase#1{\def#1##1{\NoCaseChange{#1{##1}}}}
304 % \end{macrocode}
305 % \end{macro}
306 %
307 % \begin{macro}{\NoCaseChange}
308 % For hiding arbitrary text from |\uppercase|. This innocuous
309 % definition is used for any occurrence of |\NoCaseChange|
310 % in text that is not passed to |\MakeTextUppercase|. For example a
311 % section heading may be uppercased, but the toc entry may not.
312 % It is also used for nested definitions of |\cite| etc, where the
313 % |\NoCaseChange| is inserted by expansion, but not removed as it is
314 % hidden by the brace group.
315 % \begin{macrocode}
316 \let\NoCaseChange\@firstofone
317 % \end{macrocode}
318 % \end{macro}
319 %
320 %\begin{macro}{\@skipmath}
321 % |#1|: operation |\uppercase| / |\lowercase|\\
322 % |#2|: text up to first (next) |$|\\
323 % |#3|: first math mode material (or |\valign| sentinel)
324 % \begin{macrocode}
325 \def\@skipmath#1#2$#3${%
326 \@skip@nonchangecase#1#2\NoCaseChange\valign
327 \ifx\valign#3%
328 \else
329 $#3$%
330 \expandafter\@skipmath\expandafter#1%
331 \fi}
332 % \end{macrocode}
333 % \end{macro}
334 %
335 %\begin{macro}{\@skip@nonchangecase}
336 % |#1|: |\uppercase| or |\lowercase|\\
337 % |#2|: Text up to the first command (such as |\cite|) made `safe'.
338 % or the first use of |\NoCaseChange|.
339 % \begin{macrocode}
340 \def\@skip@nonchangecase#1#2\NoCaseChange#3{%
341 #1{#2}%
342 \ifx\valign#3%
343 \else
344 #3%
345 \expandafter\@skip@nonchangecase\expandafter#1%
346 \fi}
347 % \end{macrocode}
348 % \end{macro}
349 %
350 % \begin{macro}{\MakeTextUppercase}
351 % \changes{v0.06}{1998/11/12}
352 % {Add edef to make behaviour more like \cs{MakeUppercase}}
353 % Put it all together. Arrange for \i\ and \j\ to uppercase, and
354 % to read the pairs in the ucase list `forwards'.
355 % \begin{macrocode}
356 \DeclareRobustCommand\MakeTextUppercase{%
357 \@uclcnotmath{\def\i{I}\def\j{J}}{##1##2}\uppercase}
358 % \end{macrocode}
359 %
360 % \begin{macrocode}
361 \protected@edef\MakeTextUppercase#1{\MakeTextUppercase{#1}}
362 % \end{macrocode}
363 % \end{macro}
364 %
365 % \begin{macro}{\MakeTextLowercase}
366 % \changes{v0.06}{1998/11/12}
367 % {Add edef to make behaviour more like \cs{MakeLowercase}}
368 % probably will never be used, but it is easy to implement.
369 % Use |\lowercase| and read the pairs in the uppercase list `backwards'.
370 % \begin{macrocode}
371 \DeclareRobustCommand\MakeTextLowercase{%
372 \@uclcnotmath{}{##2##1}\lowercase}
373 % \end{macrocode}
374 %
375 % \begin{macrocode}
376 \protected@edef\MakeTextLowercase#1{\MakeTextLowercase{#1}}
377 % \end{macrocode}
378 % \end{macro}
379 %
380 % \begin{macro}{\MakeUppercase}
381 % \begin{macro}{\MakeLowercase}
382 % \changes{v0.06}{1998/11/12}
383 % {Option to overload added. latex/2906}
384 % \begin{macrocode}
385 \DeclareOption{overload}{%
386 \expandafter\let\csname MakeUppercase \expandafter\endcsname
387 \csname MakeTextUppercase \endcsname
388 \expandafter\let\csname MakeLowercase \expandafter\endcsname
389 \csname MakeTextLowercase \endcsname}
390 % \end{macrocode}
391 %
392 % \begin{macrocode}
393 \ProcessOptions
394 % \end{macrocode}
395 % \end{macro}
396 % \end{macro}
397 %
398 % \begin{macrocode}
399 %</package>
400 % \end{macrocode}
401 %
402 % \Finale
403 %