Debian Codegraph @

texmf-dist/source/latex/reptheorem/reptheorem.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (c) 2024- Jesse Straat
4 %
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either version 1.3c
7 % of this license or (at your option) any later version.
8 % The latest version of this license is in
9 % https://www.latex-project.org/lppl.txt
10 % and version 1.3c or later is part of all distributions of LaTeX
11 % version 2008 or later.
12 %
13 % This work has the LPPL maintenance status `maintained'.
14 %
15 % The Current Maintainer of this work is Jesse Straat.
16 %
17 % This work consists of the main file reptheorem.dtx
18 % and the derived files
19 % reptheorem.sty, reptheorem.pdf, reptheorem.ins
20 %
21 % Unpacking:
22 % (a) If reptheorem.ins is present:
23 % latex reptheorem.ins
24 % (b) If reptheorem.ins is absent:
25 % latex reptheorem.dtx
26 %
27 % Documentation:
28 % pdflatex reptheorem.dtx
29 % makeindex -s gind.ist -o reptheorem.ind reptheorem.idx
30 % makeindex -s gglo.ist -o reptheorem.gls reptheorem.glo
31 % pdflatex reptheorem.dtx
32 % dtx file based on https://www.texdev.net/2009/10/06/a-model-dtx-file/
33 %
34 %<*ignore>
35 \iffalse
36 %</ignore>
37 %
38 %<*readme>
39 # `reptheorem`
40
41 When writing a large manuscript, it is sometimes
42 beneficial to repeat a theorem (or lemma or…) at
43 an earlier or later point for didactical purposes.
44 However, `thmtools`'s built-in `restatable`
45 only allows replicating theorems *after* they
46 have been stated, and only in the same document.
47 `reptheorem` solves the issue by making use
48 of the `.aux` file, and also introduces its own file
49 extension, `.thm`, to replicate theorems in other files.
50
51 # Installation
52 Run the following in the command line:
53 1. If reptheorem.ins is present:
54 `latex reptheorem.ins`
55 2. If reptheorem.ins is absent:
56 `latex reptheorem.dtx`
57
58 Move `reptheorem.sty` to a folder that TeX can find.
59
60 # Documentation
61 Run the following in the command line:
62 ```
63 pdflatex reptheorem.dtx
64 makeindex -s gind.ist -o reptheorem.ind reptheorem.idx
65 makeindex -s gglo.ist -o reptheorem.gls reptheorem.glo
66 pdflatex reptheorem.dtx
67 ```
68 This automatically unpacks the package, as well.
69
70 ---
71
72 &copy; 2024- Jesse Straat
73
74 License: [LPPL1.3c](https://www.latex-project.org/lppl.txt)
75
76 [GitHub Repository](https://github.com/JesseStraat/reptheorem)
77
78 %</readme>
79 %
80 %<*ignore>
81 \fi
82 \def\plainTeXstring{plain}
83 \ifx\fmtname\plainTeXstring\else
84 \expandafter\begingroup
85 \fi
86 %</ignore>
87 %
88 %<*install>
89 \input docstrip.tex
90 \Msg{************************************************************************}
91 \Msg{* Installation}
92 \Msg{* Package: reptheorem 2025-09-03 v1.4.1}
93 \Msg{************************************************************************}
94
95 \keepsilent
96 \askforoverwritefalse
97
98 \preamble
99
100 Copyright (c) 2024- Jesse Straat
101
102 This work may be distributed and/or modified under the
103 conditions of the LaTeX Project Public License, either version 1.3c
104 of this license or (at your option) any later version.
105 The latest version of this license is in
106 https://www.latex-project.org/lppl.txt
107 and version 1.3c or later is part of all distributions of LaTeX
108 version 2008 or later.
109
110 This work has the LPPL maintenance status `maintained'.
111
112 The Current Maintainer of this work is Jesse Straat.
113
114 This work consists of the main file reptheorem.dtx
115 and the derived files
116 reptheorem.sty, reptheorem.pdf, reptheorem.ins
117
118 \endpreamble
119
120 \usedir{tex/latex/reptheorem}
121 \generate{
122 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
123 }
124
125 \obeyspaces
126 \Msg{************************************************************************}
127 \Msg{*}
128 \Msg{* To finish the installation you have to move the following}
129 \Msg{* file into a directory searched by TeX:}
130 \Msg{*}
131 \Msg{* reptheorem.sty}
132 \Msg{*}
133 \Msg{* To produce the documentation run the file `reptheorem.dtx'}
134 \Msg{* through LaTeX.}
135 \Msg{*}
136 \Msg{* Happy TeXing!}
137 \Msg{*}
138 \Msg{************************************************************************}
139
140 %</install>
141 %<install>\endbatchfile
142 %
143 %<*ignore>
144 \usedir{source/latex/reptheorem}
145 \generate{
146 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
147 }
148
149 \nopreamble\nopostamble
150 \usedir{doc/latex/reptheorem}
151 \generate{
152 \file{README.md}{\from{\jobname.dtx}{readme}}
153 }
154
155 \ifx\fmtname\plainTeXstring
156 \expandafter\endbatchfile
157 \else
158 \expandafter\endgroup
159 \fi
160 %</ignore>
161
162 %<*driver>
163 \NeedsTeXFormat{LaTeX2e}
164 \documentclass{ltxdoc}
165 \usepackage{\jobname}
166 \usepackage{amsthm}
167 \newtheorem{theorem}{Theorem}
168 \usepackage[final,
169 hyperindex=false,
170 colorlinks,
171 ]{hyperref}
172 \EnableCrossrefs
173 \CodelineIndex
174 \RecordChanges
175 \begin{document}
176 \DocInput{\jobname.dtx}
177 \end{document}
178 %</driver>
179 % \fi
180 %
181 % \GetFileInfo{\jobname.sty}
182 %
183 % \DoNotIndex{\begin,\end,\begingroup,\endgroup,\csname,\endcsname,\ifcsname,\if,\else,\IfFileExists,\IfValueTF,\fi}
184 % \DoNotIndex{\def,\edef,\expandafter,\gdef}
185 % \DoNotIndex{\immediate,\input}
186 % \DoNotIndex{\jobname,\label,\let,\long,\newcounter,\NewDocumentCommand}
187 % \DoNotIndex{\NewDocumentEnvironment,\noexpand}
188 % \DoNotIndex{\ProvidesPackage,\ref,\relax,\setcounter}
189 % \DoNotIndex{\string,\value,\write,\expanded,\IfBooleanT,\IfValueT,\ifx}
190 % \DoNotIndex{\makeatletter,\makeatother,\NewExpandableDocumentCommand,\providecommand}
191 %
192 % \title{^^A
193 % \textsf{reptheorem}\thanks{^^A
194 % Version \fileversion, last revised \filedate.^^A
195 % }^^A
196 % }^^A
197 % \author{^^A
198 % Jesse Straat^^A
199 % }
200 % \date{\filedate}
201 %
202 % \maketitle
203 %^^A
204 % \begin{abstract}
205 % \noindent When writing a large manuscript, it is sometimes
206 % beneficial to repeat a theorem (or lemma or \dots) at
207 % an earlier or later point for didactical purposes.
208 % However, \textsf{thmtools}'s built-in |restatable|
209 % only allows replicating theorems \textit{after} they
210 % have been stated, and only in the same document.
211 % \textsf{reptheorem} solves the issue by making use
212 % of the |.aux| file, and also introduces its own file
213 % extension, |.thm|, to replicate theorems in other files.
214 % \end{abstract}
215 %^^A
216 % \tableofcontents
217 %^^A
218 %\changes{v1.0}{2024/03/27}{First public release}
219 %^^A
220 %^^A
221 %^^A
222 %\StopEventually{^^A
223 % \PrintChanges
224 % \PrintIndex
225 %}
226 %^^A
227 %^^A
228 %^^A
229 %^^A
230 % \section{Repeating theorems}
231 % Let's say we define a theorem as follows:
232 % \begin{verbatim}
233 % \begin{theorem}[Yoneda Lemma]
234 % For \(F\colon \mathcal{C}^\mathrm{op}\to \mathbf{Set}\) a functor,
235 % \([\mathcal{C}^\mathrm{op},\mathbf{Set}](YA, F) \cong F(A)\)%
236 % for all objects \(A\) in \(\mathcal{C}\).
237 % \end{theorem}
238 % \end{verbatim}
239 % Its output is of course
240 % \begin{makethm}{theorem}{thm:Yoneda}[Yoneda Lemma]
241 % For \(F\colon \mathcal{C}^\mathrm{op}\to \mathbf{Set}\) a functor,
242 % \([\mathcal{C}^\mathrm{op},\mathbf{Set}](YA, F) \cong F(A)\)
243 % for all objects \(A\) in \(\mathcal{C}\).
244 % \end{makethm}
245 % Now let's say we want to replicate the theorem
246 % within the same document. That is what the new
247 % environment \DescribeEnv{makethm} |makethm| is
248 % used for.
249 % \begin{verbatim}
250 % \begin{makethm}{theorem}{thm:Yoneda}[Yoneda Lemma]
251 % For \(F\colon \mathcal{C}^\mathrm{op}\to \mathbf{Set}\) a functor,
252 % \([\mathcal{C}^\mathrm{op},\mathbf{Set}](YA, F) \cong F(A)\)
253 % for all objects \(A\) in \(\mathcal{C}\).
254 % \end{makethm}
255 % \end{verbatim}
256 % Its output is the same (in fact, we've secretly used
257 % |makethm| in the previous example), but the important
258 % difference is that we have saved the theorem for later use.\par
259 % The |makethm| environment takes two mandatory arguments
260 % and one optional one. The first mandatory argument is the
261 % type of theorem environment as defined in \textsf{amsthm}, like |theorem|, |lemma|,
262 % |definition|, etc. The second is the theorem's label.
263 % The label is mandatory since, to replicate the theorem,
264 % we need to have a ``name'' attached to it. |makethm|
265 % automatically attaches a |\label|, as well, so |\ref{thm:Yoneda}|
266 % becomes \ref{thm:Yoneda}. The optional argument is passed
267 % right to the optional argument of the theorem environment,
268 % giving the theorem a name.\par
269 %^^A
270 % Now let's say we want to replicate the theorem later
271 % or earlier in the text. This may be done if, for example,
272 % the theorem is proven at a later point, or we want to
273 % ``tease'' the reader with a powerful theorem that will be
274 % proven later in the chapter. To do this, we use the
275 % \DescribeMacro{\repthm} |\repthm| command: |\repthm{thm:Yoneda}|.
276 % This outputs the theorem again.
277 % \repthm{thm:Yoneda}
278 % The label of this theorem is a |\ref|, and automatically
279 % links to the original theorem statement.\par
280 % If the original theorem statement exists in a different
281 % file, or has not been created yet, we can add a placeholder
282 % alt text to the |\repthm| as an optional argument, which
283 % only displays if the theorem is undefined. For example,
284 % |\repthm{thm:foo}[bar]| returns
285 % \repthm{thm:foo}[bar]
286 % \noindent If we do the same without providing an alt text, we get
287 % \repthm{thm:foo}
288 % \noindent together with a warning: ``Package \textsf{reptheorem}: Theorem |thm:foo|
289 % not defined; rebuild your project. If the issue persists, create the theorem
290 % using |\begin{makethm}| or consider adding alt text to |\repthm| using the optional
291 % parameter.''\par
292 % Since we're using the |.aux| file, it is possible
293 % to replicate a theorem before it is stated. For example,
294 % \begin{verbatim}
295 % \repthm{thm:later}
296 % \begin{makethm}{theorem}{thm:later}
297 % Alligator!
298 % \end{makethm}
299 % \end{verbatim}
300 % returns
301 % \repthm{thm:later}
302 % \begin{makethm}{theorem}{thm:later}
303 % Alligator!
304 % \end{makethm}
305 % Note that it is necessary to run a |.tex| file twice
306 % to replicate theorems ahead of time, similarly to
307 % how one has to run a file twice to make sure the
308 % references are correct.\par
309 % It is also possible to use a starred version, \DescribeMacro{\repthm*} |\repthm*|.
310 % It then automatically adds a star to the end of the theorem environment.
311 % For example, |theorem| becomes |theorem*|.
312 %^^A
313 % \section{Replicating theorems between files}
314 % Let's say we have the following files for our project:
315 % \begin{verbatim}
316 % foo.tex
317 % bar.tex
318 % \end{verbatim}
319 % Let's say that we have defined a theorem |thm:baz|
320 % in |bar.tex|, and we want to replicate it in |foo.tex|.
321 % To achieve this, we first use the \DescribeMacro{\theoremfile}
322 % |\theoremfile| command in the preamble of |bar.tex|. This
323 % compiles all theorems defined in |bar.tex| and outputs them
324 % into a file |bar.thm|. To then import these into |foo.tex|, we
325 % use \DescribeMacro{\loadtheorems} |\loadtheorems{bar.thm}| in
326 % the preamble, which loads all theorems saved in |bar.thm|.
327 % One can then use |\repthm| as usual.\par
328 % Since the |.aux| file is loaded at |\begin{document}|, putting
329 % |\loadtheorems| in the preamble of a file will guarantee that
330 % the loaded theorem file will be overwritten by the theorems in
331 % the |.aux| file, i.e., theorems defined in the same document.
332 % In our example, if we also defined a |thm:baz| in |foo.tex|,
333 % loading |bar.thm| into |foo.tex| will not overwrite the local
334 % |thm:baz|.
335 %^^A
336 % \subsection{Replicating theorems to subfiles}
337 % Replicating theorems to different files is particularly
338 % useful when working in big documents with multiple subfiles.
339 % For example, let's say we have the files
340 % \begin{verbatim}
341 % main.tex
342 % foo.tex
343 % bar.tex
344 % \end{verbatim}
345 % Here, |main.tex| is generated by including |foo.tex|
346 % and |bar.tex| as chapters, creating a single large document.
347 % It is now possible to replicate theorems within the
348 % subfiles by running |\theoremfile| in |main.tex|,
349 % and then using |\loadtheorems{main.thm}| in
350 % |foo.tex| and |bar.tex|. This will allow us to
351 % use all theorems in the final |main.tex| in each of
352 % the subfiles.
353 %^^A
354 %^^A
355 %^^A
356 % \section{Source code}
357 % \begin{macrocode}
358 %<*package>
359 \ProvidesPackage{reptheorem}[2025-09-03 v1.4.1 Reptheorem package]
360 % \end{macrocode}
361 % \begin{macro}{\theoremfile}
362 % Using |\theoremfile| will output all saved theorems into an output file.
363 % By default, if your \LaTeX file is |foo.tex|, the output file is |foo.thm|.
364 % \begin{macrocode}
365 \def\reptheorem@theoremfile{\relax}
366 \NewDocumentCommand{\theoremfile}{ O{\jobname.thm} }{
367 % O: the path of the file to which we should save theorems
368 %
369 \def\reptheorem@theoremfile{#1}
370 \newwrite\@thmlist
371 \immediate\openout\@thmlist=#1
372 }
373 % \end{macrocode}
374 % \end{macro}
375 % \begin{macro}{\loadtheorems}
376 % \changes{v1.4}{2025/04/15}{Now makes @ catcode 11 to fix incompatibility.}
377 % If you have exported saved theorems to a file, you can load them
378 % into another file using the macro |\loadtheorems|.
379 % \begin{macrocode}
380 \NewDocumentCommand{\loadtheorems}{ m }{
381 \IfFileExists{#1}{
382 \makeatletter
383 \input{#1}
384 \makeatother
385 }{
386 \PackageWarning{reptheorem}{%
387 File #1 not found. I will not import any theorems.%
388 }
389 }
390 }
391 % \end{macrocode}
392 % The |\makeatletter| is included here to assure that any macros that are
393 % expanded into macros that contain an |@| are interpreted correctly.
394 % \end{macro}
395 % \begin{macro}{repthm@firstoffive}
396 % \changes{v1.4.1}{2025/08/20}{Added firstoffive command}
397 % This returns the first of five arguments. It is used to get
398 % the theorem number of a label.
399 % \begin{macrocode}
400 \NewExpandableDocumentCommand{\repthm@firstoffive}{ m m m m m }{%
401 #1%
402 }
403 % \end{macrocode}
404 % \end{macro}
405 % \begin{macro}{repthm@ifrefexists}
406 % \changes{v1.4.1}{2025/09/03}{Added ifrefexists command}
407 % This command checks whether a label was defined in the auxiliary file.
408 % Using just |\ifcsname r@foo\endcsname| is not sufficient, since
409 % |\ref{foo}| defines |\r@foo| using a placeholder variable if the reference
410 % does not exist.
411 % \begin{macrocode}
412 \NewExpandableDocumentCommand{\repthm@ifrefexists}{ m +m +m }{%
413 % m: the label
414 % m: code to run if true
415 % m: code to run if false
416 \ifcsname r@#1\endcsname
417 % reference exists but might be dummy
418 \expandafter\ifx\csname r@#1\endcsname\relax
419 % reference is a dummy
420 #3%
421 \else
422 % reference exists and is not a dummy
423 #2%
424 \fi
425 \else
426 % reference doesn't exist
427 #3%
428 \fi
429 }
430 % \end{macrocode}
431 % \end{macro}
432 % \begin{environment}{makethm}
433 % \changes{v1.1}{2024/05/03}{Now saves theorem environment type, breaking backwards compatibility.}
434 % \changes{v1.2}{2024/09/21}{Environment end moved to fix vertical spacing.}
435 % \changes{v1.2}{2024/09/22}{Theorem name is only saved if it exists.}
436 % \changes{v1.2}{2024/09/22}{Renamed theorem output variable to be unique for each theorem.}
437 % \changes{v1.4}{2025/08/15}{Added theorem label to aux file.}
438 % \changes{v1.4.1}{2025/08/20}{Replaced theorem label saving macro.}
439 % On to defining the actual theorems to be saved.
440 % \begin{macrocode}
441 \NewDocumentEnvironment{makethm}{ m m o +b }
442 % m: the type of theorem environment
443 % m: the name of the theorem
444 % o: optional parameter for environment
445 % b: the content of the theorem
446 %
447 {%
448 \IfValueTF{#3}{% Check if theorem has optional arguments
449 \begin{#1}[#3]\label{#2}
450 }{
451 \begin{#1}\label{#2}
452 }
453 % \begin{theorem}
454 #4
455 \providecommand{\label}[1]{}
456 \expandafter\gdef\csname thmtype@#2\endcsname{#1}%
457 \expandafter\long\expandafter\gdef\csname thm@#2\endcsname{#4}%
458 \IfValueT{#3}{% Only save theorem name if it exists
459 \expandafter\gdef\csname thmdesc@#2\endcsname{#3}%
460 }
461 % Saving parameters to aux file
462 \expandafter\long\expandafter\gdef\csname thmoutput@#2\endcsname{%
463 \string\expandafter\string\gdef\noexpand%
464 \csname thmtype@#2\string\endcsname{#1}%
465 ^^J%
466 \string\expandafter\string\long\string\expandafter%
467 \string\gdef\noexpand\csname thm@#2\string\endcsname{#4}%
468 \IfValueT{#3}{%
469 ^^J%
470 \string\expandafter\string\gdef\noexpand%
471 \csname thmdesc@#2\string\endcsname{#3}%
472 }%
473 ^^J%
474 \string\expandafter\string\gdef\noexpand%
475 \csname thmlabel@#2\string\endcsname{%
476 \repthm@ifrefexists{#2}{%
477 \expandafter\repthm@firstoffive\expanded{\csname r@#2\endcsname}%
478 }{}%
479 }%
480 }
481 \write\@auxout{\csname thmoutput@#2\endcsname}
482 \if\reptheorem@theoremfile\relax
483 % No file has been set
484 \else
485 % We have a theorem file
486 % Saving parameters to theorem file
487 \write\@thmlist{\csname thmoutput@#2\endcsname}
488 \fi
489 \end{#1}
490 }{}
491 % \end{macrocode}
492 % \end{environment}
493 % \begin{macro}{\repthm}
494 % \changes{v1.1}{2024/05/03}{Now saves theorem environment type, breaking backwards compatibility.}
495 % \changes{v1.2}{2024/09/22}{Fixed bug where theorems got a name even if undefined.}
496 % \changes{v1.3}{2024/10/07}{Added hyperref named destination compatibility by setting counter to very low value.}
497 % \changes{v1.3}{2024/10/07}{Changed thetheorem to csname to fix compatibility with theorem types not called ``theorem''.}
498 % \changes{v1.4}{2024/11/05}{Added warnings for unknown counter and unknown theorem type.}
499 % \changes{v1.4}{2025/08/15}{If reference doesn't exist, saved label is now used instead of ??. Added star option.}
500 % \changes{v1.4.1}{2025/09/03}{Added fallback for when no label is saved.}
501 % To repeat a theorem, use the |\repthm| command.\par
502 % If the theorem type shares its counter with another theorem type,
503 % e.g., |lemma| having the same counter as |thoerem|, make sure you
504 % have |thmtools| imported. Its |\@counteralias| macro is essential
505 % for the counters to work.
506 % \begin{macrocode}
507 \newcounter{old@counter}
508 \NewDocumentCommand{\repthm}{ s m +o }{
509 % s: optional star to add to theorem environment
510 % m: the name of the theorem
511 % o: alt text
512 \begingroup
513 % Check if thmtype is given
514 \ifcsname thmtype@#2\endcsname%
515 \expandafter\let\expandafter\@@thmtype\csname thmtype@#2\endcsname%
516 \else%
517 \def\@@thmtype{theorem}%
518 \PackageWarning{reptheorem}{%
519 Theorem '#2' has unknown theorem type. Assuming it is of
520 type 'theorem'.%
521 }
522 \fi%
523 \edef\@@thmcounter{\@@thmtype}
524 \IfBooleanT{#1}{\edef\@@thmtype{\@@thmtype*}}
525 %
526 % Save theorem counter so we don't increase it
527 \ifcsname c@\@@thmcounter\endcsname
528 \else
529 \PackageWarning{reptheorem}{%
530 Counter '\@@thmcounter' not defined; if theorem
531 '\@@thmcounter' shares its counter with another
532 theorem, make sure thmtools is imported.%
533 }
534 \fi
535 \setcounter{old@counter}{\value{\@@thmcounter}}
536 \setcounter{\@@thmcounter}{-900}
537 %
538 % Set label number
539 \repthm@ifrefexists{#2}{%
540 % Reference exists: set number as reference
541 \expandafter\def\csname the\@@thmtype\endcsname{\ref{#2}}
542 }{%
543 % Force label number as saved
544 \ifcsname thmlabel@#2\endcsname
545 \expandafter\def\csname the\@@thmtype\endcsname{%
546 \csname thmlabel@#2\endcsname%
547 }
548 \else
549 % No label number saved: revert to ??
550 \expandafter\def\csname the\@@thmtype\endcsname{\ref{#2}}
551 \fi
552 }
553 %
554 \let\@@theoremnotdefined\relax
555 %
556 \ifcsname thm@#2\endcsname% Check if theorem is even defined
557 % Theorem is defined
558 \expandafter\let\expandafter\@@thm\csname thm@#2\endcsname
559 % Output theorem
560 \ifcsname thmdesc@#2\endcsname % Check if theorem has name
561 \begin{\@@thmtype}[\csname thmdesc@#2\endcsname]
562 \@@thm
563 \end{\@@thmtype}
564 \else % No optionals
565 \begin{\@@thmtype}
566 \@@thm
567 \end{\@@thmtype}
568 \fi
569 \else
570 % Theorem undefined
571 \IfValueTF{#3}{
572 \begin{\@@thmtype}
573 #3
574 \end{\@@thmtype}
575 }{% No theorem or alt text provided: throw warning
576 \begin{\@@thmtype}
577 \end{\@@thmtype}
578 \PackageWarning{reptheorem}{%
579 Theorem '#2' not defined; rebuild your project.
580 If the issue persists, create the theorem using
581 \begin{makethm} or consider adding alt text to \repthm
582 using the optional parameter.%
583 }
584 }
585 \fi
586 \setcounter{\@@thmcounter}{\value{old@counter}}
587 % Reset theorem counter back to original
588 \endgroup
589 }
590 % \end{macrocode}
591 % \end{macro}
592 % \begin{macrocode}
593 %</package>
594 % \end{macrocode}
595 %\Finale