Debian Codegraph @

texmf-dist/source/latex/cleveref-usedon/cleveref-usedon.dtx

raw
1 \def\UsedOnPackageVersion{0.4.0}
2 \def\UsedOnPackageDate{2023-04-21}
3 % \iffalse meta-comment
4 %
5 % Package `cleveref-usedon' to use with LaTeX2e
6 %
7 % Copyright (C) 2023 by Sven Pistre
8 %
9 % Written and maintained by Sven Pistre
10 %
11 % The development version of this package can be found at
12 %
13 % http://github.com/SvenPistre/cleveref-usedon
14 %
15 % for those people who are interested. Please report bugs by creating a
16 % github issue or sending an email to [email protected].
17 % ---------------------------------------------------------------------------
18 % This file may be distributed and/or modified under the
19 % conditions of the LaTeX Project Public License, either
20 % version 1.3 of this license or (at your option) any later
21 % version. The latest version of this license is in:
22 %
23 % http://www.latex-project.org/lppl.txt
24 %
25 % and version 1.3 or later is part of all distributions of
26 % LaTeX version 2005/12/01 or later.
27 % -----------------------------------------------------------------------
28 % This work consists of the files cleveref-usedon.dtx and cleveref-usedon.ins
29 % and the derived filebase cleveref-usedon.sty.
30 %
31 %<package>\NeedsTeXFormat{LaTeX2e}[2021-06-01]
32 %<package>\ProvidesExplPackage{cleveref-usedon}
33 %<package> {\UsedOnPackageDate}
34 %<package> {\UsedOnPackageVersion}
35 %<package> {Patches the cleveref package and adds forward-referencing functionality}
36 %
37 %<*driver>
38 \ProvidesFile{cleveref-usedon.dtx}
39 \documentclass{l3doc}
40 \usepackage{amssymb}
41 \usepackage{mathtools}
42 \usepackage{amsthm}
43 \usepackage{thmtools}
44 \usepackage{hyperref}
45 \usepackage[capitalise]{cleveref-usedon}[2023/03/29]
46 \declaretheorem[
47 numberwithin=section,
48 name=Theorem]{theorem}
49 \declaretheorem[
50 sibling=theorem,
51 name=Lemma]{lemma}
52 \declaretheorem[
53 sibling=theorem,
54 name=Corollary]{corollary}
55 \crefname{page}{page}{pages} % do NOT capitalise pages for more visual appeal
56 \EnableCrossrefs
57 \CodelineIndex
58 \RecordChanges
59 \begin{document}
60 \DocInput{\jobname.dtx}
61 \end{document}
62 %</driver>
63 % \fi
64 %%
65 % \DoNotIndex{
66 % \arabic, \AtBeginDocument, \AtEndDocument,
67 % \emph, \enquote, \ExplSyntaxOn, \ExplSyntaxOff,
68 % \MessageBreak
69 % }
70 %
71 % \changes{v0.1.0}{2023-03-29}{Initial version}
72 % \changes{v0.2.0}{2023-04-07}{%
73 % Manually \texttt{\textbackslash{}Require}'d the packages \pkg{expl3} and \pkg{xparse}%
74 % for users of older \LaTeX{} installations.%
75 % Added \texttt{\_\_UsedOn\_}-guards to the macros \texttt{\textbackslash{}origlabel},%
76 % \texttt{\textbackslash{}origcref}, and \texttt{\textbackslash{}origCref} to prevent them from leaking.%
77 % }
78 % \changes{v0.3.0}{2023-04-18}{%
79 % Added the options \texttt{UsedBy} and \texttt{UsedByAndOn} upon request of
80 % \href{https://people.math.umass.edu/~murray/}{Murray Eisenberg}. Thank you for this input.
81 % For now these options remain experimental because you need to use proof environments in an unusual way,
82 % see \cref{sec:UsedByAndOn}.
83 % }
84 % \changes{v0.4.0}{2023-04-21}{%
85 % Rewritten some parts slightly,
86 % most notably changed the documentation class for this documentation
87 % from \cls{ltxdoc} to \cls{l3doc}.
88 % }
89 %
90 % \GetFileInfo{cleveref-usedon.dtx}
91 %
92 %
93 %
94 % \title{The \pkg{cleveref-usedon} package%
95 % \thanks{This document corresponds to
96 % \pkg{cleveref-usedon}~v\UsedOnPackageVersion,
97 % last revised~\UsedOnPackageDate.}}
98 % \author{Sven Pistre%
99 % \thanks{
100 % E-mail:
101 % \href{mailto:[email protected]?subject=[cleveref-usedon]}{[email protected]}}
102 % }
103 % \date{Released \UsedOnPackageDate}
104 %
105 % \maketitle
106 %
107 % \begin{documentation}
108 %
109 % \begin{abstract}
110 % This package adds \enquote{forward-referencing} to the \pkg{cleveref} package.
111 % Any label can be referenced with the new optional argument |UsedOn|
112 % passed to |\cref|. Doing so, will print an info message at the original label
113 % location (in a theorem environment, say) which reads
114 % \enquote{\emph{Used on pages \meta{list of pages}.}}.
115 % This functionality is complementary to \pkg{hyperref}'s |pagebackref|
116 % or \pkg{biblatex}'s |backref| option for the bibliography.
117 % It might be useful for authors of longer texts such as textbooks or theses,
118 % where a lot of supplementary results and information are given in early
119 % chapters, appendices or exercises. The message on which pages these
120 % results will be used can be a helpful information for the reader of the final text.
121 % Additionally, a bug in \pkg{cleveref v0.21.4} is patched.
122 % \end{abstract}
123 %
124 % \tableofcontents
125 %
126 %
127 % \section{Introduction}
128 % \label{sec:introduction}
129 %
130 % Imagine you are reading a long mathematical text such as a text book or
131 % a thesis. There are plenty of supplementary lemmas, propositions, theorems
132 % and/or exercises throughout the whole text.
133 % You ask yourself ``Gosh, while Lemma 1.12 is certainly an interesting result
134 % \emph{where} is this result used later on in this long text? I really would find
135 % that helpful to decide \emph{why} I should read the proof.''
136 % You can, of course, use the PDF search function of your viewer to look up the
137 % string \enquote{Lemma 1.12} but wouldn't it be more helpful if Lemma 1.12 already
138 % indicates all or at least its most useful/crucial applications via an info message?
139 %
140 % This is what the package \pkg{cleveref-usedon} tries to address.
141 % The info message \enquote{\emph{Used on p. 40, 43-45 and 101.}} would then be
142 % printed to the header of Lemma 1.12.
143 % For example, we have given the following theorem the label
144 % \begin{quote}
145 % |\label{thm:SqrtTwoIrrational}|.
146 % \end{quote}
147 % \begin{theorem} \label{thm:SqrtTwoIrrational}
148 % The number $\sqrt{2}$ is irrational.
149 % \end{theorem}
150 % Now we can reference this theorem via
151 % \begin{quote}
152 % |\cref[UsedOn]{thm:SqrtTwoIrrational}|:
153 % \end{quote}
154 % A proof of \cref[UsedOn]{thm:SqrtTwoIrrational} can be traced back to Euclid.
155 %
156 % We will now reference this theorem without the optional argument
157 % |[UsedOn]|. So let's clear the page of this PDF, so that we can see the effects of
158 % calling
159 % \begin{quote}
160 % |\cref{thm:SqrtTwoIrrational}|
161 % \end{quote}
162 % more clearly.
163 % \clearpage
164 % Note that the current page number \thepage{} is not included in the list of
165 % page references in the header of \cref{thm:SqrtTwoIrrational}.
166 %
167 %
168 % \section{Usage}
169 % \label{sec:usage}
170 %
171 % The \pkg{cleveref-usedon} package uses \pkg{cleveref v0.21.4}
172 % as its base.
173 % To freely cite from the \pkg{cleveref} documentation: \newline
174 % The \pkg{cleveref-usedon} package is loaded in the usual way, by
175 % putting the line
176 % \begin{quote}
177 % |\usepackage{cleveref-usedon}|
178 % \end{quote}
179 % in your document's preamble. However, care must be taken when using
180 % \pkg{cleveref} in conjunction with other packages that modify
181 % \LaTeX{}'s referencing system (see Section 13 of \pkg{cleveref}'s
182 % documentation). Basically, \pkg{cleveref-usedon} must be loaded
183 % \emph{last} but definitely AFTER \pkg{hyperref}.
184 % \begin{function}{\cref, \Cref}
185 % \begin{syntax}
186 % \cs{cref}\oarg{Option}\marg{LabelName}
187 % \cs{Cref}\oarg{Option}\marg{LabelName}
188 % \end{syntax}
189 % \end{function}
190 % The |\cref| macro can be called with options |UsedOn| (see \cref{sec:UsedOn}),
191 % |UsedBy| (experimental, see \cref{sec:UsedByAndOn}) and |UsedByAndOn| (experimental, see \cref{sec:UsedByAndOn})
192 % or their short forms |uo|, |ub|, |ubao|.
193 % This is case-insensitive, i.e. you could also write\footnote{But why would you want to?}
194 % \begin{quote}
195 % |\cref[UsEdOn]|\marg{LabelName}, \newline
196 % |\cref[uO]|\marg{LabelName}.
197 % \end{quote}
198 % The package \pkg{cleveref-usedon} is implemented using the \LaTeX3 programming layer |expl3|.
199 % If you are interested, I have spent some time to document and comment
200 % on the implementation in \cref{sec:implementation}.
201 % On an abstract level the implementation is as follows:
202 % Whenever the label \meta{LabelName} gets
203 % referenced with one of the options at some location via |\cref|\oarg{Option}\marg{LabelName},
204 % an additional auxiliary label is created at
205 % this very location. This auxiliary label has the form \meta{Option}@\meta{LabelName}@\meta{Counter}
206 % where \meta{Counter} is an integer that counts how often the label \meta{LabelName} has
207 % been referenced with \meta{Option}. At the end of the \LaTeX{} run, the final value of this counter
208 % is written to the .aux file as a key-value pair:
209 % \begin{quote}
210 % \meta{Option}@\meta{LabelName} = \meta{MaxCounter}
211 % \end{quote}
212 % In the second \LaTeX{} run, we read this counter from the .aux file.
213 % Then, at the original location of the referenced label \meta{LabelName}, we can now pass
214 % the list of auxiliary labels
215 % \begin{quote}
216 % \meta{Option}@\meta{LabelName}@1, ..., \meta{Option}@\meta{LabelName}@\meta{MaxCounter}
217 % \end{quote}
218 % to |\cpageref| (and |\cref| for the experimental options) and write the forward-referencing info message.
219 % \subsection{The option \oarg{UsedOn}}
220 % \label{sec:UsedOn}
221 %
222 % \begin{variable}{UsedOn}
223 % This option adds the message
224 % \begin{quote}
225 % \emph{(Used on page(s) \meta{list of page(s)}.)}
226 % \end{quote}
227 % The text is followed by a line break
228 % and is set after the original location of the referenced label \meta{LabelName}.
229 % If \pkg{hyperref} has been loaded, there will also be hyperlinks
230 % to the corresponding pages from where the label has been referenced.
231 % \end{variable}
232 %
233 % If the original label has been set in a theorem-like environment such as
234 % \begin{quote}
235 % \begin{verbatim}
236 % \begin{theorem} \label{thm:SqrtTwoIrrational}
237 % The number $\sqrt{2}$ is irrational.
238 % \end{theorem}
239 % \end{verbatim}
240 % \end{quote}
241 % then the info message is printed in the header of this theorem-like
242 % environment. The same functionality can be used for |\Cref|.
243 %
244 %
245 % \subsection{The experimental options \oarg{UsedBy} and \oarg{UsedByAndOn}}
246 % \label{sec:UsedByAndOn}
247 %
248 % \begin{variable}{UsedBy, UsedByAndOn}
249 % The option \oarg{UsedBy} adds the message
250 % \begin{quote}
251 % \emph{(Used by \meta{list of theorem-like destination(s)}.)}
252 % \end{quote}
253 % The option \oarg{UsedByAndOn} adds the message
254 % \begin{quote}
255 % \emph{(Used by \meta{list of theorem-like destination(s)} on page(s) \meta{list of page(s)}.)}
256 % \end{quote}
257 % Each text is followed by a line break
258 % and is set after the original location of the referenced label \meta{LabelName}.
259 % If \pkg{hyperref} has been loaded, there will also be hyperlinks to the destinations.
260 % \end{variable}
261 %
262 % For example, suppose we have the following lemma.
263 % \begin{lemma} \label{lemma:SmoothFunction}
264 % Any smooth function $f\colon \mathbb{R}\to \mathbb{R}$ is continuous.
265 % \end{lemma}
266 % And we will use it in the proof of the following result.
267 % \begin{corollary} \label{cor:DerivativeContinuous}
268 % Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth.
269 % The derivative $f^{\prime}\colon \mathbb{R}\to \mathbb{R}$ is continuous.
270 % \begin{proof}
271 % The derivative of a smooth map is itself smooth.
272 % Hence, the claim follows by \cref[UsedBy]{lemma:SmoothFunction}.
273 % \end{proof}
274 % \end{corollary}
275 % The previous result will in turn be used in the proof of the next one.
276 % \begin{corollary} \label{cor:AllDerivativesContinuous}
277 % Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth and $k\in\mathbb{N}$.
278 % The $k$th derivative $f^{(k)}\colon \mathbb{R}\to \mathbb{R}$ is continuous.
279 % \begin{proof}
280 % This follows from \cref[UsedByAndOn]{cor:DerivativeContinuous} by induction.
281 % \end{proof}
282 % \end{corollary}
283 % The code for the above examples is as follows:
284 % \begin{quote}
285 % \begin{verbatim}
286 % \begin{lemma} \label{lemma:SmoothFunction}
287 % Any smooth function $f\colon \mathbb{R}\to \mathbb{R}$
288 % is continuous.
289 % \end{lemma}
290 %
291 % \begin{corollary} \label{cor:DerivativeContinuous}
292 % Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth.
293 % The derivative $f^{\prime}\colon \mathbb{R}\to \mathbb{R}$
294 % is continuous.
295 % \begin{proof}
296 % The derivative of a smooth map is itself smooth.
297 % Hence, the claim follows by \cref[UsedBy]{lemma:SmoothFunction}.
298 % \end{proof}
299 % \end{corollary}
300 %
301 % \begin{corollary} \label{cor:AllDerivativesContinuous}
302 % Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth and
303 % $k\in\mathbb{N}$. The $k$th derivative
304 % $f^{(k)}\colon \mathbb{R}\to \mathbb{R}$
305 % is continuous.
306 % \begin{proof}
307 % This follows from
308 % \cref[UsedByAndOn]{cor:DerivativeContinuous} by induction.
309 % \end{proof}
310 % \end{corollary}
311 % \end{verbatim}
312 % \end{quote}
313 % Unfortunately, due to how this package is currently implemented, to get these
314 % experimental options to work it is necessary to abuse the usage of proof environments.
315 % Namely, one needs to nest the proof environment \emph{inside} the theorem-like environment.
316 % Note carefully how the proof environments are (ab)used in the above code example.
317 %
318 % This is -- as far is I know -- not how these environments are supposed to be used.
319 % In particular, placing text between theorem-like environment and the corresponding proof,
320 % as is often common, will result in a wrong reference. Namely, instead of referencing the
321 % theorem-like environment by name only the corresponding section name would be printed, e.g.
322 % \enquote{\emph{Used by \cref{sec:UsedByAndOn}.}}.
323 % You can see this for yourself, if you move the proof environment out of the theorem-like
324 % environment in the above examples.
325 % Hence, using proof environments correctly results in messages which are less helpful to the reader.
326 % On the other hand, using this experimental functionality to help the reader forces users (i.e. authors)
327 % of this package to use proof environments incorrectly.
328 % This sounds like a No-Free-Lunch theorem...
329 % Therefore, use these two experimental options at your own discretion!
330 %
331 %
332 % \section{Hints and tips}
333 % \label{sec:tips}
334 %
335 % If you use the |capitalise| option for \pkg{cleveref}, you might want
336 % to revert this capitalisation for page references for more visual appeal by putting
337 % \begin{quote}
338 % |\crefname{page}{page}{pages}|
339 % \end{quote}
340 % in your document's preamble, after loading \pkg{cleveref-usedon}.
341 %
342 % It is recommended to not use the optional arguments for equation-like
343 % environments such as \cref[UsedOn]{eq:Stokes} because sometimes\footnote{I haven't quite tracked down this bug.}
344 % the info message will --- unhelpfully --- be printed inside the equation
345 % environment, like so (this might or might not\footnote{
346 % In version 0.2.0 of this package, the text \enquote{\emph{Used on page 2.}}
347 % was printed right after the formula in the equation environment.}
348 % show undesired behaviour):
349 % \begin{equation}
350 % \int_{M}\mathrm{d}\omega =\int_{\partial M}\omega. \label{eq:Stokes}
351 % \end{equation}
352 % So, one should use this functionality only for theorem-like
353 % environments such as theorems, lemmas and exercises etc.
354 %
355 % If one references the same label multiple times but with different options, say |UsedOn| and |UsedBy|,
356 % then \emph{both} info messages are printed after the original label location.
357 % This is not how this functionality was intended and you shouldn't use it like that.
358 % I am not going to implement a check which various combinations of these options are used for the same label.
359 %
360 % \subsection{Editing the info messages}
361 % \label{subsec:EditInfoMsg}
362 %
363 % \begin{function}{\UsedOnMessage, \UsedByMessage, \UsedByAndOnMessage}
364 % \begin{syntax}
365 % \cs{UsedOnMessage}\marg{PageList from cpageref}
366 % \cs{UsedByMessage}\marg{EnvironmentList from cpageref}
367 % \cs{UsedByAndOnMessage}\marg{EnvironmentList from cpageref}\marg{PageList from cpageref}{}
368 % \end{syntax}
369 % The standard messages which get printed to the first line of the labelled
370 % environment are
371 % \begin{quote}
372 % \emph{(Used on \meta{PageList}.)}, \newline
373 % \emph{(Used by \meta{EnvironmentList}.)}, \newline
374 % \emph{(Used by \meta{EnvironmentList}) on \meta{PageList}.)},
375 % \end{quote}
376 % respectively
377 % --- followed by a line break --- where \meta{PageList} is generated internally
378 % by \pkg{cleveref} via |\cpageref| and \meta{EnvironmentList} is generated internally
379 % by \pkg{cleveref} via |\cref|.
380 % You can change these behaviours by redefining the macros |\UsedOnMessage|, |\UsedByMessage|
381 % and |\UsedByAndOnMessage|, e.g. as
382 % \begin{quote}
383 % \begin{verbatim}
384 % \RenewDocumentCommand{\UsedOnMessage}{ m }{
385 % \emph{(Will be cited on #1.)} \newline
386 % }
387 % \RenewDocumentCommand{\UsedByMessage}{ m }{
388 % \emph{(Will be applied in #1.)} \newline
389 % }
390 % \RenewDocumentCommand{\UsedByAndOnMessage}{ m m }{
391 % \emph{(Will be applied in #1 on #2.)} \newline
392 % }
393 % \end{verbatim}
394 % \end{quote}
395 % \end{function}
396 %
397 %
398 % \section{Interaction with other packages}
399 % \label{sec:OtherPackages}
400 %
401 % All interactions with other packages mentioned in Section 13 of
402 % \pkg{cleveref}'s documentation also apply to \pkg{cleveref-usedon}.
403 % In fact (if \pkg{cleveref-usedon} is loaded last),
404 % \pkg{ntheorem}'s |\thref| and
405 % \pkg{varioref}'s |\vref| also obtain the additional |UsedOn|
406 % functionality because \pkg{cleveref} redefines these macros to
407 % be aliases for |\cref|. Of course, they need to be loaded in the correct order, i.e.
408 % \begin{verbatim}
409 % \usepackage{ntheorem}
410 % \usepackage{hyperref}
411 % \usepackage{cleveref-usedon}
412 % \end{verbatim}
413 % or
414 % \begin{verbatim}
415 % \usepackage{varioref}
416 % \usepackage{hyperref}
417 % \usepackage{cleveref-usedon}
418 % \end{verbatim}
419 %
420 %
421 % \section{Future features}
422 % \label{sec:future}
423 %
424 % For all feature requests, either
425 % \href{https://github.com/SvenPistre/cleveref-usedon/issues}{create a github issue} or
426 % \href{mailto:[email protected]?subject=[cleveref-usedon]}{send me an email}.
427 %
428 % Let's just reference \cref[UsedOn]{thm:SqrtTwoIrrational} one last time for the fun of it,
429 % check \cpageref{thm:SqrtTwoIrrational} again to see the effect to the reference list
430 % in the header of \cref{thm:SqrtTwoIrrational}.
431 %
432 % \end{documentation}
433 %
434 %
435 % \begin{implementation}
436 %
437 %
438 % \section{Implementation}
439 % \label{sec:implementation}
440 %
441 % Start the \pkg{DocStrip} guards.
442 % \begin{macrocode}
443 %<*package>
444 % \end{macrocode}
445 %
446 % Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
447 % \begin{macrocode}
448 %<@@=UsedOn>
449 % \end{macrocode}
450 %
451 % If the \LaTeX{} version is too old, then abort loading and show an error message.
452 % The macro |\IfFormatAtLeastTF| is not be available on \LaTeX{} versions older than |2020-10-01|
453 % so we need to provide an internal workaround.
454 % \begin{macrocode}
455 \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
456 \IfFormatAtLeastTF{2021-06-01}{%
457 % LaTeX2e version new enough
458 }{%
459 \PackageError{cleveref-usedon}{%
460 Mismatched~LaTeX~support~files~detected.\MessageBreak
461 Your~LaTeX~format~is~dated~\fmtversion,\MessageBreak
462 but~the~package~cleveref-usedon\MessageBreak
463 requires~at~least~2021-06-01.\MessageBreak
464 Update~your~TeX~distribution.\MessageBreak
465 \MessageBreak
466 Loading~cleveref-usedon~will~abort!}%
467 {Update~your~TeX~distribution~using~your~TeX~package~manager.}%
468 }
469 % \end{macrocode}
470 %
471 % If the version of the \LaTeX3 kernel is too old, then abort loading and show an error message.
472 % The macro |\IfExplAtLeastTF| currently does not exist at all\footnote{
473 % But might in the future, see \href{https://github.com/latex3/latex2e/issues/1004}{github issue \#1004}.},
474 % but we can provide an internal workaround.
475 % \begin{macrocode}
476 \providecommand\IfExplAtLeastTF{\@ifl@t@r\ExplLoaderFileDate}
477 \RequirePackage{expl3}[2021-05-16]
478 \IfExplAtLeastTF{2021-05-16}{%
479 % expl3 version new enough
480 }{%
481 \PackageError{cleveref-usedon}{%
482 Support~package~expl3~too~old.\MessageBreak
483 The~L3~programming~layer~in~the~LaTeX~format\MessageBreak
484 is~dated~\ExplLoaderFileDate,\MessageBreak
485 but~the~package~cleveref-usedon\MessageBreak
486 requires~at~least~2021-05-16.\MessageBreak
487 Update~your~TeX~distribution.\MessageBreak
488 \MessageBreak
489 Loading~cleveref-usedon~will~abort!}%
490 {Update~your~TeX~distribution~using~your~TeX~package~manager.}%
491 }
492 % \end{macrocode}
493 %
494 % \subsection{Options and requirements}
495 %
496 % The following package is included in the \LaTeX{} kernel since 2020-10-01.
497 % Here, it is manually |\Require|'d for users with older \LaTeX{} versions.
498 % For such users the loading should have been aborted anyway.
499 % \begin{macrocode}
500 \RequirePackage{xparse}
501 % \end{macrocode}
502 %
503 % The following package options currently don't do anything.
504 % \begin{macrocode}
505 \bool_new:N \g_@@_StandardBehaviour_bool
506 \bool_gset_true:N \g_@@_StandardBehaviour_bool
507 \DeclareOption{usedon}{
508 \OptionNotUsed
509 \bool_gset_true:N \g_@@_StandardBehaviour_bool
510 }
511 \DeclareOption{notusedon}{
512 \OptionNotUsed
513 \bool_gset_false:N \g_@@_StandardBehaviour_bool
514 }
515 % \end{macrocode}
516 %
517 % All other package options get passed on to \pkg{cleveref} which is the base for the current package here.
518 % \begin{macrocode}
519 \DeclareOption*{
520 \PackageInfo{cleveref-usedon}
521 {Passing~option~'\CurrentOption'~to~cleveref}
522 \PassOptionsToPackage{\CurrentOption}{cleveref}
523 }
524 \ProcessOptions*
525 \RequirePackage{cleveref}[2018/03/27]
526 % \end{macrocode}
527 %
528 % \subsection{Patches of known bugs to \pkg{cleveref}}
529 %
530 % The following fixes the range bug for |\cpageref| in \pkg{cleveref v0.21.4}.
531 % See \url{https://tex.stackexchange.com/a/620066/267438}.
532 % (We need to temporarily reset the \pkg{DocStrip} guards.)
533 %
534 % \begin{macrocode}
535 %<@@=>
536 \newcommand*{\@setcpagerefrange}[3]{%
537 \@@setcpagerefrange{#1}{#2}{cref}{#3}}
538 \newcommand*{\@setCpagerefrange}[3]{%
539 \@@setcpagerefrange{#1}{#2}{Cref}{#3}}
540 \newcommand*{\@setlabelcpagerefrange}[3]{%
541 \@@setcpagerefrange{#1}{#2}{labelcref}{#3}}
542 %<@@=UsedOn>
543 % \end{macrocode}
544 %
545 % \subsection{Overloading of label and cref}
546 %
547 % We need variants of |\str_case:nn|
548 % which expand the input string token.
549 % This will be used to match
550 % options for \cs{@@_Processor}.
551 %
552 % \begin{macrocode}
553 \prg_generate_conditional_variant:Nnn \str_case:nn { x } { TF }
554 \cs_generate_variant:Nn \str_case:nn { x }
555 % \end{macrocode}
556 %
557 %\begin{variable}{\g_@@_k_seq}
558 % Let's initialise a global key sequence for those label names that
559 % have been referenced via |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|.
560 %
561 % \begin{macrocode}
562 \seq_new:N \g_@@_k_seq
563 % \end{macrocode}
564 %\end{variable}
565 %
566 %\begin{variable}{\g_@@_kv_prop}
567 % And we'll also create a global key-value property list with
568 % label names as keys and the maximal amount of times they have
569 % been referenced via |[UsedOn]| as values (possibly known from
570 % the last pdflatex run).
571 %
572 % \begin{macrocode}
573 \prop_new:N \g_@@_kv_prop
574 % \end{macrocode}
575 %\end{variable}
576 %
577 %
578 %\begin{variable}{\g_@@_Options_clist}
579 % This |clist| contains all options that can be passed to |\cref| which are currently implemented.
580 % \begin{macrocode}
581 \clist_new:N \g_@@_Options_clist
582 \clist_set:Nn \g_@@_Options_clist {UsedOn, UsedBy, UsedByAndOn}
583 % \end{macrocode}
584 %\end{variable}
585 %
586 %\begin{macro}{\UsedOnMessage}
587 % The following are the standard texts that get printed in the first line
588 % of the labelled environment which later gets referenced with
589 % |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|.
590 %
591 % \begin{macrocode}
592 \NewDocumentCommand{\UsedOnMessage}{m}{
593 \emph{(Used~on~#1.)} \newline
594 }
595 % \end{macrocode}
596 %\end{macro}
597 %\begin{macro}{\UsedByMessage}
598 % \begin{macrocode}
599 \NewDocumentCommand{\UsedByMessage}{ m }{
600 \emph{(Used~by~#1.)} \newline
601 }
602 % \end{macrocode}
603 %\end{macro}
604 %\begin{macro}{\UsedByAndOnMessage}
605 % \begin{macrocode}
606 \NewDocumentCommand{\UsedByAndOnMessage}{ m m }{
607 \emph{(Used~by~#1~on~#2.)} \newline
608 }
609 % \end{macrocode}
610 %\end{macro}
611 %
612 %\begin{macro}{\@@_Printer}
613 % Given a \meta{LabelName}, the following command records all references
614 % via the optional |cref| arguments |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|, i.e.
615 % when the user called |\cref|\oarg{Option}\marg{LabelName}.
616 % They are recorded in a temporary comma-separated list
617 % (a |clist| in |expl3| speak). This |clist| is then passed to \pkg{cleveref}'s
618 % |cpageref| or |cref| which in turn is passed to |\UsedOnMessage|, |\UsedByMessage|
619 % or |\UsedByAndOnMessage| to be printed after the original label.
620 %
621 % \begin{macrocode}
622 \NewDocumentCommand{\@@_Printer}{ m m }{%
623 % \end{macrocode}
624 % First, we will check if the reference \meta{Option}|@|\meta{LabelName}|@1|
625 % exists. Here, the |@1| means that \meta{LabelName} has been referenced
626 % with option \oarg{Option} at least once. If this reference does not exist,
627 % nothing happens.
628 %\iffalse
629 %% % Check if the reference #1@<LabelName>@1 exists
630 %% % Here the @1 means that <LabelName> has been referenced
631 %% % with option #1 at least once where #1 is
632 %% % 'UsedOn', 'UsedBy' or 'UsedByAndOn'
633 %\fi
634 % \begin{macrocode}
635 \cs_if_exist:cT {r@#1@#2@1}
636 {
637 % \end{macrocode}
638 % Next, we store all the references of the form
639 % \meta{Option}|@|\meta{LabelName}|@|\meta{Number} in a temporary
640 % comma-separated list (|clist|). We do this by looping from 1 to the value
641 % of |LastRun@|\meta{Option}|@|\meta{LabelName} (if the latter value exists,
642 % otherwise we set it to 1). Initially, this will need two consecutive runs of pdflatex.
643 %\iffalse
644 %% % In a tmp clist we store all the references of the form
645 %% % `<Option>@<LabelName>@<Number>`
646 %% % where Number between 1 and \value{LastRun@UsedOn@<LabelName>}
647 %% % if the latter exists, otherwise until 1
648 %% % Should/will normally need two consecutive runs of pdflatex
649 %\fi
650 % \begin{macrocode}
651 \cs_if_free:cTF {c@LastRun@#1@#2}
652 { \int_set:Nn \l_tmpa_int { 1 } }
653 { \int_set:Nn \l_tmpa_int { \value{LastRun@#1@#2} } }
654 \int_set:Nn \l_tmpb_int { 1 }
655 \int_while_do:nn { \l_tmpb_int <= \l_tmpa_int }
656 {
657 \clist_put_right:Nx \l_tmpa_clist { #1@#2@\int_use:N \l_tmpb_int }
658 \int_incr:N \l_tmpb_int
659 }
660 % \end{macrocode}
661 % Finally, we print the message that was set in the macro |\UsedOnMessage|.
662 %\iffalse
663 %% % Print `UsedOn` message by calling \cpageref with the parameter clist above
664 %% % Uncomment the next two lines for debugging to see the contents of \l_tmpa_clist
665 %% %% Arguments~of~cpageref/cref~are:
666 %% %% \par\clist_use:Nn \l_tmpa_clist {\par}\par
667 %\fi
668 % \begin{macrocode}
669 \str_case:xn { \str_foldcase:n { #1 } }
670 {
671 {usedon}
672 {\UsedOnMessage{\cpageref{\l_tmpa_clist}}}
673 {usedby}
674 {\UsedByMessage{\cref{\l_tmpa_clist}}}
675 {usedbyandon}
676 {\UsedByAndOnMessage{\cref{\l_tmpa_clist}}
677 {\cpageref{\l_tmpa_clist}}}
678 }
679 }
680 }%
681 % \end{macrocode}
682 %\end{macro}
683 %
684 %\begin{macro}{\@@_PrintMessage}
685 % This macro prints the corresponding |UsedOn| message after the original label.
686 % \begin{macrocode}
687 \NewDocumentCommand{\@@_PrintMessage}{ m }{%
688 \clist_map_inline:Nn \g_@@_Options_clist
689 { \@@_Printer{##1}{#1} }
690 }%
691 % \end{macrocode}
692 %\end{macro}
693 %
694 %
695 %\begin{variable}{\l_@@_Option_str}
696 % This variable will be used to store the used option in a |\cref| call.
697 %
698 % \begin{macrocode}
699 \str_new:N \l_@@_Option_str
700 % \end{macrocode}
701 %\end{variable}
702 %
703 %\begin{macro}{\@@_Processor}
704 % This macro takes an optional argument
705 % (a case-insensitive version of the options or their shortform)
706 % and a mandatory argument (a single \marg{LabelName} or a |clist| \{\meta{LabelName1},\meta{LabelName2},\ldots\}).
707 % \begin{macrocode}
708 \NewDocumentCommand{\@@_Processor}{ o m }{%
709 \IfValueT{#1}{
710 % \end{macrocode}
711 % First, we check if the option |[UsedOn]| or |[uo]| (case-insensitive) was used.
712 % \begin{macrocode}
713 \str_case:xnTF { \str_foldcase:n { #1 } }
714 {
715 % \end{macrocode}
716 %\iffalse
717 %% % check if options 'UsedOn', 'UsedBy' or 'UsedByAndOn'
718 %% % (case-insensitive) were used in one of the following forms
719 %\fi
720 % \begin{macrocode}
721 {usedon} {\str_set:Nn \l_@@_Option_str {UsedOn}}
722 {uo} {\str_set:Nn \l_@@_Option_str {UsedOn}}
723 {usedby} {\str_set:Nn \l_@@_Option_str {UsedBy}}
724 {ub} {\str_set:Nn \l_@@_Option_str {UsedBy}}
725 {usedbyandon} {\str_set:Nn \l_@@_Option_str {UsedByAndOn}}
726 {ubao} {\str_set:Nn \l_@@_Option_str {UsedByAndOn}}
727 }
728 {
729 {
730 % \end{macrocode}
731 % Loop through the (potential) label list in the mandatory argument
732 % of |\cref| (or |\Cref|) which gets passed as the mandatory argument
733 % of the current macro.
734 %\iffalse
735 %% % Loop through (potential) label list in arg of \cref (or \Cref)
736 %\fi
737 % \begin{macrocode}
738 \seq_set_from_clist:Nn \l_tmpa_seq {#2}
739 \seq_map_inline:Nn \l_tmpa_seq
740 {
741 % \end{macrocode}
742 % If the label has \emph{not} been referenced yet via the option |#1| where |#1| is one of
743 % the current available options in \ExplSyntaxOn \{\g__UsedOn_Options_clist\} \ExplSyntaxOff
744 % , create a
745 % counter for the current run |ThisRun@<Option>@##1|.
746 % If we are not in the initial run anymore, there should be a counter
747 % |LastRun@<Option>@##1| which contains the maximal amount this
748 % specific label has been referenced via |UsedOn|.
749 % If we are in the initial run, we need to create this counter as well.
750 % Then save the label in the global container \cs{g_@@_k_seq}.
751 %\iffalse
752 %% % if the label has not been referenced yet,
753 %% % create a counter for the current and last run and save the label in the
754 %% % global container \g_@@_k_seq
755 %\fi
756 % \begin{macrocode}
757 \seq_if_in:NxF \g_@@_k_seq
758 { \l_@@_Option_str @##1}
759 {
760 \newcounter{
761 ThisRun@ \l_@@_Option_str @##1
762 }
763 \cs_if_free:cT {c@LastRun@ \l_@@_Option_str @##1}
764 {
765 \newcounter{LastRun@ \l_@@_Option_str @##1}
766 }
767 \seq_gput_right:Nx \g_@@_k_seq
768 { \l_@@_Option_str @##1}
769 }
770 % \end{macrocode}
771 % Increase the counter for the current run by 1 and set the counter
772 % for last run (containing the maximal amount of |UsedOn|-|\cref|'s)
773 % to...the maximal amount of |UsedOn|-|\cref|'s.
774 %\iffalse
775 %% % increase the counters and compare with max counter
776 %\fi
777 % \begin{macrocode}
778 \stepcounter{ThisRun@ \l_@@_Option_str @##1}
779 \setcounter{LastRun@ \l_@@_Option_str @##1}{%
780 \fp_eval:n
781 { max(%
782 \value{ThisRun@ \l_@@_Option_str @##1},%
783 \value{LastRun@ \l_@@_Option_str @##1}
784 ) }%
785 }
786 % \end{macrocode}
787 % Store the value of the max counter |LastRun@<Option>@##1| in
788 % the global container \cs{g_@@_kv_prop}.
789 %\iffalse
790 %% % store the value in global key-value property list
791 %\fi
792 % \begin{macrocode}
793 \prop_gput:Nxx \g_@@_kv_prop
794 { \l_@@_Option_str @##1}
795 {\arabic{LastRun@ \l_@@_Option_str @##1}}
796 % \end{macrocode}
797 % Now we create a numbered auxiliary label. This label is issued at the
798 % location where we referenced the original label via
799 % |\cref[UsedOn]|\meta{LabelName}.
800 % The new auxiliary label has the prefix |UsedOn@|, |UsedBy@| or |UsedByAndOn@| and
801 % the suffix |@\arabic{ThisRun@<Option>@##1}|, e.g.
802 % |UsedOn@thm:Pythagoras@4| if it is the fourth time that we called \newline
803 % |\cref[UsedOn]{thm:Pythagoras}|.
804 %\iffalse
805 %% % create a label for the UsedOn reference and number this label
806 %\fi
807 % \begin{macrocode}
808 \@@_origlabel{
809 \l_@@_Option_str @##1@
810 \arabic{ThisRun@ \l_@@_Option_str @##1}
811 }
812 }
813 }
814 }
815 {
816 % \end{macrocode}
817 % Throw an error, if an unrecognised option was used for the
818 % optional argument to this macro.
819 %\iffalse
820 %% % Throw an error, if an unrecognised option was used
821 %% % for the optional argument to this macro.
822 %\fi
823 % \begin{macrocode}
824 \msg_new:nnn {cleveref-usedon} { OptionSpellingError }
825 { \MessageBreak
826 Spelling~error~\msg_line_context:
827 \MessageBreak
828 Did~you~mean~to~pass~option\MessageBreak
829 'UsedOn'~to~cref~or~Cref?
830 }
831 \msg_fatal:nn { cleveref-usedon } { OptionSpellingError }
832 }
833 }
834 }%
835 % \end{macrocode}
836 %\end{macro}
837 %
838 %\begin{macro}{\@@_cref}
839 % This is just a wrapper around \pkg{cleveref}'s |\cref|.
840 % Additionally the \cs{@@_Processor} gets called.
841 % \begin{macrocode}
842 \NewDocumentCommand{\@@_cref}{ s o m }{%
843 \IfBooleanTF{#1}{ \@@_origcref*{#3} }{ \@@_origcref{#3} }%
844 \@@_Processor[#2]{#3}
845 }%
846 % \end{macrocode}
847 %\end{macro}
848 %
849 %\begin{macro}{\@@_Cref}
850 % This is just a wrapper around \pkg{cleveref}'s |\Cref|.
851 % Additionally the \cs{@@_Processor} gets called.
852 % \begin{macrocode}
853 \NewDocumentCommand{\@@_Cref}{ s o m }{%
854 \IfBooleanTF{#1}{ \@@_origCref*{#3} }{ \@@_origCref{#3} }%
855 \@@_Processor[#2]{#3}
856 }%
857 % \end{macrocode}
858 %\end{macro}
859 %
860 %\begin{macro}{\@@_ReadFromAux}
861 % From the .aux file we will read the contents of the
862 % global container \cs{g_@@_kv_prop}.
863 % This is a key-value property list and we create and set a
864 % for each label (key) and the maximal amount (value) it was called in the last run.
865 % \begin{macrocode}
866 \NewDocumentCommand{\@@_ReadFromAux}{ }{%
867 \prop_map_inline:Nn \g_@@_kv_prop
868 {
869 \newcounter{LastRun@##1}
870 \setcounter{LastRun@##1}{##2}
871 }
872 }%
873 % \end{macrocode}
874 %\end{macro}
875 %
876 %\begin{macro}{\@@_WriteToAux}
877 % For each label we write a line in the .aux file of the form: \newline
878 % \meta{LabelName} = \meta{Maximal references via UsedOn in last run}.\newline
879 % This information can be constructed from the global container \cs{g_@@_k_seq}
880 % and the counters with prefix |ThisRun@| we set earlier.
881 % We need to wrap this in the on/off switch for |expl3| functionality.
882 % \begin{macrocode}
883 \NewDocumentCommand{\@@_WriteToAux}{ }{%
884 % \end{macrocode}
885 %% % First, we clear the global key-value prop list \cs{g_@@_kv_prop} and
886 %% % then we rebuild it with the information from the current run.
887 % \begin{macrocode}
888 \prop_clear:N \g_@@_kv_prop
889 \seq_map_inline:Nn \g_@@_k_seq
890 { \prop_gput:Nxx \g_@@_kv_prop {##1}{\arabic{ThisRun@##1}} }
891 % \end{macrocode}
892 %\iffalse
893 %% % Turn on |expl3| functionality in .aux file.
894 %\fi
895 % \begin{macrocode}
896 \iow_now:cx { @auxout }
897 { \token_to_str:N \ExplSyntaxOn }
898 % \end{macrocode}
899 %% % Loop through the key-val |proplist| and write contents to .aux file.
900 % \begin{macrocode}
901 \prop_map_inline:Nn \g_@@_kv_prop
902 {
903 \iow_now:cx { @auxout }
904 {
905 \prop_gput_from_keyval:Nn \token_to_str:N \g_@@_kv_prop
906 {##1=##2}
907 }
908 }
909 % \end{macrocode}
910 %\iffalse
911 %% % Turn off |expl3| functionality in .aux file.
912 %\fi
913 % \begin{macrocode}
914 \iow_now:cx { @auxout }
915 { \token_to_str:N \ExplSyntaxOff }
916 }%
917 % \end{macrocode}
918 %\end{macro}
919 %
920 % At the hook |\AtBeginDocument| we read from the .aux file
921 % and patch commands.
922 % \begin{macrocode}
923 \AtBeginDocument{%
924 \@@_ReadFromAux
925 % \end{macrocode}
926 % Patch label and cref to include the new |[UsedOn]| capabilities.
927 % \begin{macrocode}
928 \NewCommandCopy{\@@_origlabel}{\label}
929 \NewCommandCopy{\@@_origcref}{\cref}
930 \NewCommandCopy{\@@_origCref}{\Cref}
931 \RenewDocumentCommand{\label}{ m }{%
932 \@@_origlabel{#1}\@@_PrintMessage{#1}
933 }%
934 \RenewCommandCopy{\cref}{\@@_cref}
935 \RenewCommandCopy{\Cref}{\@@_Cref}
936 }%
937 % \end{macrocode}
938 %
939 % At the hook |\AtEndDocument| we write to the .aux file.
940 % \begin{macrocode}
941 \AtEndDocument{%
942 \@@_WriteToAux
943 }%
944 % \end{macrocode}
945 %
946 %
947 % \begin{macrocode}
948 %</package>
949 % \end{macrocode}
950 %
951 % \end{implementation}
952 %
953 % \PrintChanges
954 % \PrintIndex