Debian Codegraph @

texmf-dist/source/latex/thmtools/thm-restate.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2008-2014 by Ulrich M. Schwarz
4 % Copyright (C) 2019 by Frank Mittelbach
5 % Copyright (C) 2020- by Yukai Chou
6 %
7 % This file may be distributed and/or modified under the conditions of
8 % the LaTeX Project Public License, version 1.3c.
9 % The license can be obtained from
10 % http://www.latex-project.org/lppl/lppl-1.3c.txt
11 %
12 % \fi
13 %
14 %\iffalse (hide this from DocInput)
15 %<*restate>
16 %\fi
17 %
18 %\DescribeEnv{restatable}
19 %Only one environment is provided: \verb|restatable|, which takes one
20 %optional and two mandatory arguments. The first mandatory argument is the
21 %type of the theorem, i.e. if you want |\begin{lemma}| to be called on
22 %the inside, give |lemma|. The second argument is the name of the macro
23 %that the text should be stored in, for example \verb|mylemma|. Be careful
24 %not to specify existing command names! The optional argument will become the
25 %optional argument to your theorem command. Consider the following example:
26 %\begin{verbatim}
27 % \documentclass{article}
28 % \usepackage{amsmath, amsthm, thm-restate}
29 % \newtheorem{lemma}{Lemma}
30 % \begin{document}
31 % \begin{restatable}[Zorn]{lemma}{zornlemma}\label{thm:zorn}
32 % If every chain in $X$ is upper-bounded,
33 % $X$ has a maximal element.
34 %
35 % It's true, you know!
36 % \end{restatable}
37 % \begin{lemma}
38 % This is some other lemma of no import.
39 % \end{lemma}
40 % And now, here's Mr. Zorn again: \zornlemma*
41 % \end{document}
42 %\end{verbatim}
43 %which yields
44 % \begin{restatable}[Zorn]{lemma}{zornlemma}\label{thm:zorn}
45 % If every chain in $X$ is upper-bounded, $X$ has a maximal element.
46 %
47 % It's true, you know!
48 % \end{restatable}
49 % \begin{lemma}
50 % This is some other lemma of no import.
51 % \end{lemma}
52 % Actually, we have set a label in the environment, so we know that
53 % it's Lemma~\ref{thm:zorn} on page~\ref{thm:zorn}.
54 % And now, here's Mr. Zorn again: \zornlemma*
55 % Since we prevent the label from being set again, we find that
56 % it's still Lemma~\ref{thm:zorn} on page~\ref{thm:zorn}, even though
57 % it occurs later also.
58 %
59 % \DescribeEnv{restatable*}
60 % As you can see, we use the starred form |\mylemma*|. As in many cases in
61 % \LaTeX, the star means ``don't give a number'', since we want to retain
62 % the original number. There is also a starred variant of the |restatable|
63 % environment, where the first call doesn't determine the number, but a
64 % later call to |\mylemma| without star would. Since the number is carried
65 % around using \LaTeX' |\label| machanism, you'll need a rerun for things to
66 % settle.
67 %
68 % \subsection{Restrictions}
69 % The only counter that is saved is the one for the theorem number. So,
70 % putting floats inside a restatable is not advised: they will appear in the
71 % LoF several times with new numbers.
72 % Equations should work, but the code handling them might turn out to be
73 % brittle, in particular when you add/remove hyperref.
74 % %In the same vein, numbered equations
75 % %within the statement appear again and are numbered again, with new
76 % %numbers. (This is vaguely non-trivial to do correctly if equations are not
77 % %numbered consecutively, but per-chapter, or there are multiple numbered
78 % %equations.)
79 % Note that you cannot successfully reference the equations
80 % since all labels are disabled in the starred appearance. (The reference
81 % will point at the unstarred occurence.)
82 %
83 % You cannot nest
84 % restatables either. You \emph{can} use the |\restatable|\dots|\endrestatable|
85 % version, but everything up to the next matching |\end{...}| is scooped up.
86 % I've also probably missed many border cases.
87 %
88 %
89 %\StopEventually{}
90 % \begin{macrocode}
91 \RequirePackage{thmtools}
92 \let\@xa\expandafter
93 \let\@nx\noexpand
94 \@ifundefined{c@thmt@dummyctr}{%
95 \newcounter{thmt@dummyctr}%
96 }{}
97 \gdef\theHthmt@dummyctr{dummy.\arabic{thmt@dummyctr}}%
98 \gdef\thethmt@dummyctr{}%
99 \long\def\thmt@collect@body#1#2\end#3{%
100 \@xa\thmt@toks\@xa{\the\thmt@toks #2}%
101 \def\thmttmpa{#3}%\def\thmttmpb{restatable}%
102 \ifx\thmttmpa\@currenvir%thmttmpb
103 \@xa\@firstoftwo% this is the end of the environment.
104 \else
105 \@xa\@secondoftwo% go on collecting
106 \fi{% this is the end, my friend, drop the \end.
107 % and call #1 with the collected body.
108 \@xa#1\@xa{\the\thmt@toks}%
109 }{% go on collecting
110 \@xa\thmt@toks\@xa{\the\thmt@toks\end{#3}}%
111 \thmt@collect@body{#1}%
112 }%
113 }
114 % \end{macrocode}
115 % A totally ignorant version of |\ref|, defaulting to \#2 if label not
116 % known yet. Otherwise, return the formatted number.
117 % \begin{macrocode}
118 \def\thmt@trivialref#1#2{%
119 \ifcsname r@#1\endcsname
120 \@xa\@xa\@xa\thmt@trivi@lr@f\csname r@#1\endcsname\relax\@nil
121 \else #2\fi
122 }
123 \def\thmt@trivi@lr@f#1#2\@nil{#1}
124 % \end{macrocode}
125 %
126 % Counter safeties: some counters' values should be stored, such as
127 % equation, so we don't get a new number. (We cannot reference it anyway.)
128 % We cannot store everything, though, think page counter or section number!
129 % There is one problem here: we have to remove all references to other
130 % counters from |\theequation|, otherwise your equation could get a number
131 % like (3.1) in one place and (4.1) in another section.
132 %
133 % The best solution I can come up with is to override the usual macros
134 % that counter display goes through, to check if their argument is one
135 % that should be fully-expanded away or retained.
136 %
137 % The following should only be called from within a group, and the sanitized
138 % |\thectr| must not be called from within that group, since it needs the
139 % original |\@arabic| et al.
140 %
141 % \begin{macrocode}
142 \def\thmt@innercounters{%
143 equation}
144 \def\thmt@counterformatters{%
145 @alph,@Alph,@arabic,@roman,@Roman,@fnsymbol}
146
147 \@for\thmt@displ:=\thmt@counterformatters\do{%
148 \@xa\let\csname thmt@\thmt@displ\@xa\endcsname\csname \thmt@displ\endcsname
149 }%
150 \def\thmt@sanitizethe#1{%
151 \@for\thmt@displ:=\thmt@counterformatters\do{%
152 \@xa\protected@edef\csname\thmt@displ\endcsname##1{%
153 \@nx\ifx\@xa\@nx\csname c@#1\endcsname ##1%
154 \@xa\protect\csname \thmt@displ\endcsname{##1}%
155 \@nx\else
156 \@nx\csname thmt@\thmt@displ\endcsname{##1}%
157 \@nx\fi
158 }%
159 }%
160 \expandafter\protected@edef\csname the#1\endcsname{\csname the#1\endcsname}%
161 \ifcsname theH#1\endcsname
162 \expandafter\protected@edef\csname theH#1\endcsname{\csname theH#1\endcsname}%
163 \fi
164 }
165
166 \def\thmt@rst@storecounters#1{%
167 \bgroup
168 % ugly hack: save chapter,..subsection numbers
169 % for equation numbers.
170 %\refstepcounter{thmt@dummyctr}% why is this here?
171 %% temporarily disabled, broke autorefname.
172 \def\@currentlabel{}%
173 \@for\thmt@ctr:=\thmt@innercounters\do{%
174 \thmt@sanitizethe{\thmt@ctr}%
175 \protected@edef\@currentlabel{%
176 \@currentlabel
177 \protect\def\@xa\protect\csname the\thmt@ctr\endcsname{%
178 \csname the\thmt@ctr\endcsname}%
179 \ifcsname theH\thmt@ctr\endcsname
180 \protect\def\@xa\protect\csname theH\thmt@ctr\endcsname{%
181 (restate \protect\theHthmt@dummyctr)\csname theH\thmt@ctr\endcsname}%
182 \fi
183 \protect\setcounter{\thmt@ctr}{\number\csname c@\thmt@ctr\endcsname}%
184 }%
185 }%
186 \label{thmt@@#1@data}%
187 \egroup
188 }%
189 % \end{macrocode}
190 %
191 % Now, the main business.
192 %
193 % \begin{macrocode}
194 \newif\ifthmt@thisistheone
195 \newenvironment{thmt@restatable}[3][]{%
196 \thmt@toks{}% will hold body
197 %
198 \stepcounter{thmt@dummyctr}% used for data storage label.
199 %
200 \long\def\thmrst@store##1{%
201 \@xa\gdef\csname #3\endcsname{%
202 \@ifstar{%
203 \thmt@thisistheonefalse\csname thmt@stored@#3\endcsname
204 }{%
205 \thmt@thisistheonetrue\csname thmt@stored@#3\endcsname
206 }%
207 }%
208 \@xa\long\@xa\gdef\csname thmt@stored@#3\@xa\endcsname\@xa{%
209 \begingroup
210 \ifthmt@thisistheone
211 % these are the valid numbers, store them for the other
212 % occasions.
213 \thmt@rst@storecounters{#3}%
214 \else
215 % this one should use other numbers...
216 % first, fake the theorem number.
217 \@xa\protected@edef\csname the#2\endcsname{%
218 \thmt@trivialref{thmt@@#3}{??}}%
219 % if the number wasn't there, have a "re-run to get labels right"
220 % warning.
221 \ifcsname r@thmt@@#3\endcsname\else
222 \G@refundefinedtrue
223 \fi
224 % prevent stepcountering the theorem number,
225 % but still, have some number for hyperref, just in case.
226 \@xa\let\csname c@#2\endcsname=\c@thmt@dummyctr
227 \@xa\let\csname theH#2\endcsname=\theHthmt@dummyctr
228 % disable labeling.
229 \let\label=\thmt@gobble@label
230 \let\ltx@label=\@gobble% amsmath needs this
231 % We shall need to restore the counters at the end
232 % of the environment, so we get
233 % (4.2) [(3.1 from restate)] (4.3)
234 \def\thmt@restorecounters{}%
235 \@for\thmt@ctr:=\thmt@innercounters\do{%
236 \protected@edef\thmt@restorecounters{%
237 \thmt@restorecounters
238 \protect\setcounter{\thmt@ctr}{\arabic{\thmt@ctr}}%
239 }%
240 }%
241 % pull the new semi-static definition of \theequation et al.
242 % from the aux file.
243 \thmt@trivialref{thmt@@#3@data}{}%
244 \fi
245 % call the proper begin-env code, possibly with optional argument
246 % (omit if stored via key-val)
247 \ifthmt@restatethis
248 \thmt@restatethisfalse
249 \else
250 \csname #2\@xa\endcsname\ifx\@nx#1\@nx\else[{#1}]\fi
251 \fi
252 \ifthmt@thisistheone
253 % store a label so we can pick up the number later.
254 \label{thmt@@#3}%
255 \fi
256 % this will be the collected body.
257 ##1%
258 \csname end#2\endcsname
259 % if we faked the counter values, restore originals now.
260 \ifthmt@thisistheone\else\thmt@restorecounters\fi
261 \endgroup
262 }% thmt@stored@#3
263 % in either case, now call the just-created macro,
264 \csname #3\@xa\endcsname\ifthmt@thisistheone\else*\fi
265 % and artificially close the current environment.
266 \@xa\end\@xa{\@currenvir}
267 }% thm@rst@store
268 \thmt@collect@body\thmrst@store
269 }{%
270 %% now empty, just used as a marker.
271 }
272
273 \let\thmt@gobble@label\@gobble
274 % cleveref extends syntax of \label to \label[...]{...}
275 \AtBeginDocument{
276 \@ifpackageloaded{cleveref}{
277 \renewcommand*\thmt@gobble@label[2][]{}
278 }{}
279 }
280
281 \newenvironment{restatable}{%
282 \thmt@thisistheonetrue\thmt@restatable
283 }{%
284 \endthmt@restatable
285 }
286 \newenvironment{restatable*}{%
287 \thmt@thisistheonefalse\thmt@restatable
288 }{%
289 \endthmt@restatable
290 }
291
292 %%% support for keyval-style: restate=foobar
293 \protected@edef\thmt@thmuse@families{%
294 \thmt@thmuse@families%
295 ,restate phase 1%
296 ,restate phase 2%
297 }
298 \newcommand\thmt@splitrestateargs[1][]{%
299 \g@addto@macro\thmt@storedoptargs{,#1}%
300 \def\tmp@a##1\@{\def\thmt@storename{##1}}%
301 \tmp@a
302 }
303
304 \newif\ifthmt@restatethis
305 \define@key{restate phase 1}{restate}{%
306 \thmt@thmuse@iskvtrue
307 \def\thmt@storedoptargs{}% discard the first time around
308 \thmt@splitrestateargs #1\@
309 \def\thmt@storedoptargs{}% discard the first time around
310 %\def\thmt@storename{#1}%
311 \thmt@debug{we will restate as `\thmt@storename' with more args
312 `\thmt@storedoptargs'}%
313 \@namedef{thmt@unusedkey@restate}{}%
314 % spurious "unused key" fixes itself once we are after tracknames...
315 \thmt@restatethistrue
316 \protected@edef\tmp@a{%
317 \@nx\thmt@thisistheonetrue
318 \@nx\def\@nx\@currenvir{\thmt@envname}%
319 \@nx\@xa\@nx\thmt@restatable\@nx\@xa[\@nx\thmt@storedoptargs]%
320 {\thmt@envname}{\thmt@storename}%
321 }%
322 \@xa\g@addto@macro\@xa\thmt@local@postheadhook\@xa{%
323 \tmp@a
324 }%
325 }
326 \thmt@mkignoringkeyhandler{restate phase 1}
327
328 \define@key{restate phase 2}{restate}{%
329 % do not store restate as a key for repetition:
330 % infinite loop.
331 % instead, retain the added keyvals
332 % overwriting thmt@storename should be safe here, it's been
333 % xdefd into the postheadhook
334 \thmt@splitrestateargs #1\@
335 }
336 \kv@set@family@handler{restate phase 2}{%
337 \ifthmt@restatethis
338 \@xa\@xa\@xa\g@addto@macro\@xa\@xa\@xa\thmt@storedoptargs\@xa\@xa\@xa{\@xa\@xa\@xa,%
339 \@xa\kv@key\@xa=\kv@value}%
340 \fi
341 }
342
343 % \end{macrocode}
344 %\iffalse
345 %</restate>
346 %\fi