Debian Codegraph @

texmf-dist/source/latex/amsrefs/pcatcode.dtx

raw
1 % \def\filename{pcatcode.dtx}
2 % \def\fileversion{1.04b}
3 % \def\filedate{2007/08/17}
4 %
5 % \iffalse meta-comment
6 %
7 % American Mathematical Society
8 % Technical Support
9 % Publications Technical Group
10 % 201 Charles Street
11 % Providence, RI 02904
12 % USA
13 % tel: (401) 455-4080
14 % (800) 321-4267 (USA and Canada only)
15 % fax: (401) 331-3842
16 % email: [email protected]
17 %
18 % Copyright 2001, 2010 American Mathematical Society.
19 %
20 % This work may be distributed and/or modified under the
21 % conditions of the LaTeX Project Public License, either version 1.3c
22 % of this license or (at your option) any later version.
23 % The latest version of this license is in
24 % http://www.latex-project.org/lppl.txt
25 % and version 1.3c or later is part of all distributions of LaTeX
26 % version 2005/12/01 or later.
27 %
28 % This work has the LPPL maintenance status `maintained'.
29 %
30 % The Current Maintainer of this work is the American Mathematical
31 % Society.
32 %
33 % \fi
34 %
35 % \iffalse
36 %<*driver>
37 \documentclass{amsdtx}
38 %\usepackage{pcatcode}\relax
39 \begin{document}
40 \title{The \pkg{pcatcode} package}
41 \author{Michael~J. Downes\\American Mathematical Society}
42 \date{Version \fileversion, \filedate}
43 \DocInput{pcatcode.dtx}
44 \end{document}
45 %</driver>
46 % \fi
47 %
48 % \maketitle
49 % \section{Introduction}
50 %
51 % The \pkg{pcatcode} package provides mechanisms for robustly
52 % changing the catcode environment for the duration of a package and
53 % restoring it afterwards to whatever it was before the package was
54 % loaded.
55 %
56 % Motivation: The \pkg{amsmath} package (for example), makes a number
57 % of assignments using characters such as double-quote and
58 % left-quote, because these are hard-wired into the \tex/ syntax for
59 % numbers and other things. If a package that makes double-quote an
60 % active character is loaded before \pkg{amsmath}, all the
61 % statements that use double-quote turn into error messages.
62 %
63 % But now! Groan and grumble no more, ye package writers, for putting
64 % a magical invocation of the pcatcode package at the beginning of
65 % your package file, as shown here, will ensure that your
66 % package contents will be processed with completely normal catcodes.
67 %\begin{verbatim}
68 %\NeedsTeXFormat{LaTeX2e}[1995/12/01]
69 %\@ifundefined{PushCatcodes}{%
70 % \RequirePackage{pcatcode}\relax\PushCatcodes\NormalCatcodes
71 %}{}
72 %\ProvidesPackage{foo}[2002/04/16 v1.04]
73 %\end{verbatim}
74 %
75 % It must be followed by a matching \cs{PopCatcodes} command,
76 % typically used in conjunction with \cs{endinput}.
77 %
78 % WARNING: This functionality would work best if it were built into
79 % the \LaTeX{}2e kernel, but it cannot be usefully added to the
80 % kernel now without adversely affecting document compatibility
81 % across different systems. This package therefore modifies one or
82 % two of the low-level package-loading functions defined by the
83 % kernel. This means that there may be trouble if any other package,
84 % or some future version of \LaTeX{}, changes the definitions of
85 % those functions.
86 %
87 % NOTE: Packages that do not call \cs{PushCatcodes}
88 % \cs{NormalCatcodes} will remain transparent to the external catcode
89 % environment in the usual way (i.e., for all characters except the
90 % \verb'@' character).
91 %
92 % \StopEventually{}
93 %
94 % \section{Implementation}
95 % \subsection{Preliminary Remarks}
96 %
97 % At the document level, we assume that the following characters
98 % always have their standard catcode:
99 % \begin{center}
100 % \begin{tabular}{lp{.75\columnwidth}}
101 % \verb'\{}' & for commands and arguments\\
102 % \verb'%' & for comments\\
103 % \verb'#' & for use with \cn{newcommand}\\
104 % \verb'*' & cannot be changed without breaking star-form commands\\
105 % \verb'[]' & cannot be changed without breaking optional arguments\\
106 % \verb'~' & already active, no reason to change catcode
107 % \end{tabular}
108 % \end{center}
109 %
110 % One might think that we could assume hyphen, period (and comma, for
111 % European decimal notation) are always catcode 12. Experience has
112 % shown, however, that for just about every character there is some
113 % plausible application that would be facilitated by making that
114 % character active and giving it a complex definition. Surely hyphen
115 % and period must stay catcode 12 in order to work in statements like
116 % the following?
117 %\begin{verbatim}
118 %\addtocounter{section}{-1}
119 %\addtolength{\columnwidth}{-1.5cm}
120 %\end{verbatim}
121 % Yet hyphen and period are important constituents of ordinary text
122 % and therefore special applications arise. For example,
123 % what if you would like
124 % mdashes to be surrounded by extra space but your authors prefer to
125 % continue writing \verb'---' in the accustomed manner?
126 %
127 % Theoretically speaking, the \pkg{pcatcode} package itself has to
128 % guard against the kind of catcode problems that it is intended to
129 % circumvent. If you would like a nice little \tex/nician's
130 % exercise, try your hand, before looking at the code below, at the
131 % task that I set for myself: Find the minimal set of catcode
132 % assumptions that one has to make before attempting to establish
133 % normalcy, where normalcy is defined as the state at the end of
134 % \fn{latex.ltx}, just before the last \cs{makeatother}. This is the
135 % state that may normally be expected at the beginning of a
136 % documentclass file, if the \LaTeX{} format file does not have any
137 % extensions (e.g., babel) compiled in.
138 %
139 % Ready to look, now?
140 %
141 % In order for the following code to work it is only necessary that
142 % backslash, letters, and digits have their normal catcodes: 0, 11,
143 % 12 respectively. One could argue that if \fn{pcatcode.sty} is
144 % invoked through a standard \cs{RequirePackage} call, it can be
145 % assumed that curly braces also have their normal catcodes. But I
146 % suppose it is not utterly inconceivable that in some special
147 % circumstances one might want to load the package with the
148 % \cs{@@input} primitive, sans braces. And in any case the extra
149 % overhead to handle braces as well is trivial so for esthetic
150 % reasons I'm gonna put it in.
151 %
152 % If you look really hard you'll find one or two other assumptions,
153 % such as ``endlinechar is not a letter''. Wait, come to think of it,
154 % I can fix that \ldots
155 %
156 % The purpose of the group is chiefly to localize the temporarily
157 % changed definitions of \cs{e}, \cs{n}, etc.
158 % \begin{macrocode}
159 \begingroup\let\e\endlinechar\iffalse\
160 \fi\chardef\E\e\e13\chardef\n\catcode\e\catcode\e5\relax\relax
161 \chardef\s\catcode32\chardef\t10\catcode32\t
162 \chardef\c\catcode37 \catcode37 14 % percent
163 \chardef\=\catcode61 \catcode61 12 % equal sign
164 \chardef\l=\catcode123 \catcode123=1 % left brace
165 \chardef\r=\catcode125 \catcode125=2 % right brace
166 \chardef\[=\catcode91 \catcode91=12 % left bracket
167 \chardef\]=\catcode93 \catcode93=12 % right bracket
168 \chardef\^=\catcode94 \catcode94=7 % hat
169 \chardef\.=\catcode46 \catcode46=12 % period
170 \chardef\/=\catcode47 \catcode47=12 % slash
171 \edef\c{%
172 \endgroup
173 \def\noexpand\pcat@restore{%
174 \catcode\number\e=\number\n \catcode32=\number\s
175 \catcode123=\number\l \catcode125=\number\r
176 \catcode37=\number\c \catcode61=\number\=%
177 \catcode91=\number\[\catcode93=\number\]\catcode94=\number\^%
178 \catcode46=\number\.\catcode47=\number\/%
179 \endlinechar=\number\E \relax
180 }%
181 }
182 \c
183 \endlinechar13\catcode13\string=5\relax\relax
184 \catcode32\string=10 \catcode37 14\relax\relax
185 \catcode61 12\catcode123=1\catcode125=2\catcode91=12\catcode93=12\relax
186 \catcode46=12\catcode47=12\catcode94=7\relax
187 % \end{macrocode}
188 %
189 % This code was postponed until now to avoid all but the most
190 % essential assumptions.
191 % \begin{macrocode}
192 \NeedsTeXFormat{LaTeX2e}
193 \ProvidesPackage{pcatcode}[2002/04/16 v1.04]
194 % \end{macrocode}
195 %
196 % \begin{macrocode}
197 \def\NormalCatcodes{%
198 \endlinechar=13%
199 \catcode33=12\catcode34=12\catcode35=6\catcode36=3\catcode37=14%
200 \catcode38=4\catcode39=12\catcode40=12\catcode41=12\catcode42=12%
201 \catcode43=12\catcode44=12\catcode45=12\catcode46=12\catcode47=12%
202 \catcode58=12\catcode59=12\catcode60=12\catcode61=12\catcode62=12%
203 \catcode63=12\catcode91=12\catcode92=0\catcode93=12\catcode94=7%
204 \catcode95=8\catcode96=12\catcode123=1\catcode124=12\catcode125=2%
205 \catcode126=13\catcode32=10\catcode13=5\catcode9=10\catcode10=12%
206 \relax
207 }
208 % \end{macrocode}
209 %
210 % \begin{macrocode}
211 \def\CatcodeStack{}
212 % \end{macrocode}
213 %
214 % Notably absent from the following list: the \verb'@' character and
215 % whitespace characters. The former is already handled in the
216 % \LaTeX{} kernel, and I hesitate to interfere with its current
217 % catcode transitions.
218 % \begin{macrocode}
219 \begingroup \escapechar=\m@ne \let\s\string
220 \xdef\pcat@otherchars{%
221 \s\!\s\"\s\#\s\$\s\%\s\&\s\'\s\(\s\)\s\*\s +\s\,\s\-\s\.\s\/\s\:%
222 \s\;\s\<\s\=\s\>\s\?\s\[\s\\\s\]\s\^\s\_\s\`\s\{\s\|\s\}\s\~%
223 }
224 \endgroup
225 % \end{macrocode}
226 %
227 % \begin{macrocode}
228 \gdef\PushCatcodes{%
229 \xdef\CatcodeStack{%
230 \expandafter\PushCat@a\pcat@otherchars\ \
231 \^^I\^^J{T \@gobbletwo}\@empty
232 \relax
233 {\CatcodeStack}}%
234 }
235 \def\PushCat@a#1{\catcode\number`#1=\number\catcode`#1 \PushCat@a}
236 % \end{macrocode}
237 %
238 % \begin{macrocode}
239 \PushCatcodes \NormalCatcodes
240 % \end{macrocode}
241 %
242 % \begin{macrocode}
243 \def\PopCatcodes{\expandafter\PopCat@a\CatcodeStack}
244 \def\PopCat@a#1#{#1\xdef\CatcodeStack}
245 % \end{macrocode}
246 %
247 % \subsection{Checking current settings}
248 %
249 % This can be used to store a copy of the current settings. Or print
250 % it with \cs{typeout}.
251 % \begin{macrocode}
252 \def\CCSdo#1{ (\string#1\@iden{:\number\catcode`#1)\CCSdo}}
253 \def\CurrentCatcodesSubset{%
254 \romannumeral 0\CCSdo\^^I\^^J\^^L\^^M\ \!\"\#\$\%\&\'\(\)\*+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}{\~\@gobbletwo}:\number\catcode`\~)%
255 }
256 % \end{macrocode}
257 %
258 % \subsection{Futurelet support}
259 %
260 % For code that does futureletting to see if a punctuation character
261 % follows, it is distressing to handle the case when some characters
262 % might be made active (e.g., by the babel package).
263 %
264 % The \cs{FutureLetSetup} function attempts to minimize the
265 % difficulties by defining canonical control sequences to represent
266 % all the visible ASCII characters (i.e., ranging from space to
267 % \qc{\~}, 32--126, plus TAB) whose catcode could be changed without
268 % transgressing the limits of standard \LaTeX{} syntax.
269 % \begin{macrocode}
270 \begingroup\pcat@restore
271 \begingroup
272 \catcode`\3="3 \catcode`\4="4 \catcode`\7="7 \catcode`\8="8
273 \catcode`\A="A \catcode`\B="B \catcode`\C="C \catcode`\D="D
274 \gdef\fls@let#1#2{%
275 \ifx\@@undefined#1\else\errmessage{\string#1 already defined}\fi
276 \begingroup
277 \lccode`\3=`#2\lccode`\7=`#2\lccode`\8=`#2%
278 \lccode`\B=`#2\lccode`\C=`#2\lccode`\D=`#2\relax
279 \ifnum\catcode`#2=\active
280 \def\do##1{\noexpand\do\noexpand##1\noexpand}%
281 \lowercase{%
282 \xdef\fls@active@characters{%
283 \fls@active@characters
284 \do#1D}%
285 }%
286 \fi
287 \aftergroup\global \aftergroup\let \aftergroup#1\aftergroup=%
288 \lowercase{\aftergroup} %
289 \lowercase{\expandafter\endgroup
290 \ifcase\catcode`#2 %
291 0\or \bgroup\or \egroup\or 3\or 4\or 5\or 6\or 7\or 8\or 9\or
292 \@sptoken\or B\or C\else D\fi
293 }%
294 }
295 \endgroup
296 % \end{macrocode}
297 % \cs{dl@@dblquote} means ``document-level double quote'': a
298 % character token number 34 that has the catcode which is in effect
299 % at \verb'\begin{document}' for double quotes.
300 % \begin{macrocode}
301 \gdef\FutureLetSetup{%
302 \gdef\fls@active@characters{}%
303 % \end{macrocode}
304 % This will normally be the same as \cs{@sptoken}.
305 % \begin{macrocode}
306 \fls@let\dl@@space\ %
307 \fls@let\dl@@exclam\!%
308 \fls@let\dl@@dblquote\"%
309 \fls@let\dl@@hash\#%
310 \fls@let\dl@@dollar\$%
311 % \end{macrocode}
312 % At document level, this cannot occur as a separate token.
313 % \begin{macrocode}
314 % \fls@let\dl@@percent\%%
315 \fls@let\dl@@ampersand\&%
316 \fls@let\dl@@rquote\'%
317 \fls@let\dl@@lparen\(%
318 \fls@let\dl@@rparen\)%
319 \fls@let\dl@@star\*%
320 \fls@let\dl@@plus\+%
321 \fls@let\dl@@comma\,%
322 \fls@let\dl@@hyphen\-%
323 \fls@let\dl@@period\.%
324 \fls@let\dl@@slash\/%
325 \fls@let\dl@@colon\:%
326 \fls@let\dl@@semicolon\;%
327 \fls@let\dl@@less\<%
328 \fls@let\dl@@equal\=%
329 \fls@let\dl@@greater\>%
330 \fls@let\dl@@question\?%
331 \fls@let\dl@@lbracket\[%
332 % \end{macrocode}
333 % At document level, this cannot occur as a separate token.
334 % \begin{macrocode}
335 % \fls@let\dl@@backslash\\%
336 \fls@let\dl@@rbracket\]%
337 \fls@let\dl@@hat\^%
338 \fls@let\dl@@underscore\_%
339 \fls@let\dl@@lquote\`%
340 % \end{macrocode}
341 % Here one would normally use \cs{bgroup}.
342 % \begin{macrocode}
343 \fls@let\dl@@lbrace\{%
344 \fls@let\dl@@vert\|%
345 % \end{macrocode}
346 % Here one would normally use \cs{egroup}.
347 % \begin{macrocode}
348 \fls@let\dl@@rbrace\}%
349 \fls@let\dl@@tilde\~%
350 }
351 \AtBeginDocument{\FutureLetSetup}
352 % \end{macrocode}
353 %
354 % \begin{macrocode}
355 \gdef\FutureLetReset{%
356 \def\do##1##2{\let##1= ##2}%
357 \fls@active@characters
358 \let\do\relax
359 }
360 \endgroup
361 % \end{macrocode}
362 %
363 % \begin{macrocode}
364 \endinput \PopCatcodes\pcat@restore
365 % \end{macrocode}
366 %
367 % \CheckSum{530}
368 % \Finale