\def\UsedOnPackageVersion{0.4.0}
\def\UsedOnPackageDate{2023-04-21}
% \iffalse meta-comment
%
% Package `cleveref-usedon' to use with LaTeX2e
%
% Copyright (C) 2023 by Sven Pistre
%
% Written and maintained by Sven Pistre
%
% The development version of this package can be found at
%
%    http://github.com/SvenPistre/cleveref-usedon
%
% for those people who are interested. Please report bugs by creating a
% github issue or sending an email to cleveref-usedon@sven-pistre.com.
% ---------------------------------------------------------------------------
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version. The latest version of this license is in:
%
%      http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of
% LaTeX version 2005/12/01 or later.
% -----------------------------------------------------------------------
% This work consists of the files cleveref-usedon.dtx and cleveref-usedon.ins
% and the derived filebase cleveref-usedon.sty.
%
%<package>\NeedsTeXFormat{LaTeX2e}[2021-06-01]
%<package>\ProvidesExplPackage{cleveref-usedon}
%<package>    {\UsedOnPackageDate}
%<package>    {\UsedOnPackageVersion}
%<package>    {Patches the cleveref package and adds forward-referencing functionality}
%
%<*driver>
\ProvidesFile{cleveref-usedon.dtx}
\documentclass{l3doc}
\usepackage{amssymb}
\usepackage{mathtools}
\usepackage{amsthm}
\usepackage{thmtools}
\usepackage{hyperref}
\usepackage[capitalise]{cleveref-usedon}[2023/03/29]
\declaretheorem[
	numberwithin=section,
	name=Theorem]{theorem}
\declaretheorem[
	sibling=theorem,
	name=Lemma]{lemma}
\declaretheorem[
	sibling=theorem,
	name=Corollary]{corollary}
\crefname{page}{page}{pages}	% do NOT capitalise pages for more visual appeal
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
    \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%%
% \DoNotIndex{
%   \arabic, \AtBeginDocument, \AtEndDocument,
%   \emph, \enquote, \ExplSyntaxOn, \ExplSyntaxOff,
%   \MessageBreak
%   }
%
% \changes{v0.1.0}{2023-03-29}{Initial version}
% \changes{v0.2.0}{2023-04-07}{%
%   Manually \texttt{\textbackslash{}Require}'d the packages \pkg{expl3} and \pkg{xparse}%
%   for users of older \LaTeX{} installations.%
%   Added \texttt{\_\_UsedOn\_}-guards to the macros \texttt{\textbackslash{}origlabel},%
%   \texttt{\textbackslash{}origcref}, and \texttt{\textbackslash{}origCref} to prevent them from leaking.%
% }
% \changes{v0.3.0}{2023-04-18}{%
%   Added the options \texttt{UsedBy} and \texttt{UsedByAndOn} upon request of
%   \href{https://people.math.umass.edu/~murray/}{Murray Eisenberg}. Thank you for this input.
%   For now these options remain experimental because you need to use proof environments in an unusual way,
%   see \cref{sec:UsedByAndOn}.
% }
% \changes{v0.4.0}{2023-04-21}{%
%   Rewritten some parts slightly,
%   most notably changed the documentation class for this documentation
%   from \cls{ltxdoc} to \cls{l3doc}.
% }
%
% \GetFileInfo{cleveref-usedon.dtx}
%
%
%
% \title{The \pkg{cleveref-usedon} package%
%         \thanks{This document corresponds to
%         \pkg{cleveref-usedon}~v\UsedOnPackageVersion,
%         last revised~\UsedOnPackageDate.}}
% \author{Sven Pistre%
%        \thanks{
%           E-mail:
%           \href{mailto:cleveref-usedon@sven-pistre.com?subject=[cleveref-usedon]}{cleveref-usedon@sven-pistre.com}}
% }
% \date{Released \UsedOnPackageDate}
%
% \maketitle
%
% \begin{documentation}
%
% \begin{abstract}
%	This package adds \enquote{forward-referencing} to the \pkg{cleveref} package.
%	Any label can be referenced with the new optional argument |UsedOn|
%	passed to |\cref|. Doing so, will print an info message at the original label
%	location (in a theorem environment, say) which reads
%	\enquote{\emph{Used on pages \meta{list of pages}.}}.
%	This functionality is complementary to \pkg{hyperref}'s |pagebackref|
%	or \pkg{biblatex}'s |backref| option for the bibliography.
%	It might be useful for authors of longer texts such as textbooks or theses,
%	where a lot of supplementary results and information are given in early
%	chapters, appendices or exercises. The message on which pages these
%	results will be used can be a helpful information for the reader of the final text.
%	Additionally, a bug in \pkg{cleveref v0.21.4} is patched.
% \end{abstract}
%
% \tableofcontents
%
%
%	\section{Introduction}
%	\label{sec:introduction}
%
%	Imagine you are reading a long mathematical text such as a text book or
%	a thesis. There are plenty of supplementary lemmas, propositions, theorems
%	and/or exercises throughout the whole text.
%	You ask yourself ``Gosh, while Lemma 1.12 is certainly an interesting result
%	\emph{where} is this result used later on in this long text? I really would find
%	that helpful to decide \emph{why} I should read the proof.''
%	You can, of course, use the PDF search function of your viewer to look up the
%	string \enquote{Lemma 1.12} but wouldn't it be more helpful if Lemma 1.12 already
%	indicates all or at least its most useful/crucial applications via an info message?
%
%	This is what the package \pkg{cleveref-usedon} tries to address.
%	The info message \enquote{\emph{Used on p. 40, 43-45 and 101.}} would then be
%	printed to the header of Lemma 1.12.
%	For example, we have given the following theorem the label
%	\begin{quote}
%		|\label{thm:SqrtTwoIrrational}|.
%	\end{quote}
%	\begin{theorem}	\label{thm:SqrtTwoIrrational}
%	    The number $\sqrt{2}$ is irrational.
%	\end{theorem}
%	Now we can reference this theorem via
%	\begin{quote}
%		|\cref[UsedOn]{thm:SqrtTwoIrrational}|:
%	\end{quote}
%	A proof of \cref[UsedOn]{thm:SqrtTwoIrrational} can be traced back to Euclid.
%
%   We will now reference this theorem without the optional argument
%	|[UsedOn]|. So let's clear the page of this PDF, so that we can see the effects of
%   calling
%	\begin{quote}
%		|\cref{thm:SqrtTwoIrrational}|
%	\end{quote}
%   more clearly.
%	\clearpage
%	Note that the current page number \thepage{} is not included in the list of
%	page references in the header of \cref{thm:SqrtTwoIrrational}.
%
%
%	\section{Usage}
%	\label{sec:usage}
%
%	The \pkg{cleveref-usedon} package uses \pkg{cleveref v0.21.4}
%	as its base.
%	To freely cite from the \pkg{cleveref} documentation:	\newline
%	The \pkg{cleveref-usedon} package is loaded in the usual way, by
%	putting the line
%	\begin{quote}
%		|\usepackage{cleveref-usedon}|
%	\end{quote}
%	in your document's preamble. However, care must be taken when using
%	\pkg{cleveref} in conjunction with other packages that modify
%	\LaTeX{}'s referencing system (see Section 13 of \pkg{cleveref}'s
%	documentation). Basically, \pkg{cleveref-usedon} must be loaded
%	\emph{last} but definitely AFTER \pkg{hyperref}.
%   \begin{function}{\cref, \Cref}
%       \begin{syntax}
%           \cs{cref}\oarg{Option}\marg{LabelName}
%           \cs{Cref}\oarg{Option}\marg{LabelName}
%       \end{syntax}
%   \end{function}
%	The |\cref| macro can be called with options |UsedOn| (see \cref{sec:UsedOn}),
%   |UsedBy| (experimental, see \cref{sec:UsedByAndOn}) and |UsedByAndOn| (experimental, see \cref{sec:UsedByAndOn})
%   or their short forms |uo|, |ub|, |ubao|.
%   This is case-insensitive, i.e. you could also write\footnote{But why would you want to?}
%	\begin{quote}
%		|\cref[UsEdOn]|\marg{LabelName},	\newline
%		|\cref[uO]|\marg{LabelName}.
%	\end{quote}
%	The package \pkg{cleveref-usedon} is implemented using the \LaTeX3 programming layer |expl3|.
%	If you are interested, I have spent some time to document and comment
%	on the implementation in \cref{sec:implementation}.
%   On an abstract level the implementation is as follows:
%   Whenever the label \meta{LabelName} gets
%   referenced with one of the options at some location via |\cref|\oarg{Option}\marg{LabelName},
%   an additional auxiliary label is created at
%   this very location. This auxiliary label has the form \meta{Option}@\meta{LabelName}@\meta{Counter}
%   where \meta{Counter} is an integer that counts how often the label \meta{LabelName} has
%   been referenced with \meta{Option}. At the end of the \LaTeX{} run, the final value of this counter
%   is written to the .aux file as a key-value pair:
%   \begin{quote}
%       \meta{Option}@\meta{LabelName} = \meta{MaxCounter}
%   \end{quote}
%   In the second \LaTeX{} run, we read this counter from the .aux file.
%   Then, at the original location of the referenced label \meta{LabelName}, we can now pass
%   the list of auxiliary labels
%   \begin{quote}
%       \meta{Option}@\meta{LabelName}@1, ..., \meta{Option}@\meta{LabelName}@\meta{MaxCounter}
%   \end{quote}
%   to |\cpageref| (and |\cref| for the experimental options) and write the forward-referencing info message.
%   \subsection{The option \oarg{UsedOn}}
%   \label{sec:UsedOn}
%
%   \begin{variable}{UsedOn}
%	This option adds the message
%   \begin{quote}
%       \emph{(Used on page(s) \meta{list of page(s)}.)}
%   \end{quote}
%   The text is followed by a line break
%   and is set after the original location of the referenced label \meta{LabelName}.
%   If \pkg{hyperref} has been loaded, there will also be hyperlinks
%	to the corresponding pages from where the label has been referenced.
%   \end{variable}
%
%	If the original label has been set in a theorem-like environment such as
%	\begin{quote}
%	\begin{verbatim}
%	\begin{theorem}   \label{thm:SqrtTwoIrrational}
%	    The number $\sqrt{2}$ is irrational.
%	\end{theorem}
%	\end{verbatim}
%	\end{quote}
%	then the info message is printed in the header of this theorem-like
%	environment. The same functionality can be used for |\Cref|.
%
%
%   \subsection{The experimental options \oarg{UsedBy} and \oarg{UsedByAndOn}}
%   \label{sec:UsedByAndOn}
%
%   \begin{variable}{UsedBy, UsedByAndOn}
%	The option \oarg{UsedBy} adds the message
%   \begin{quote}
%       \emph{(Used by \meta{list of theorem-like destination(s)}.)}
%   \end{quote}
%	The option \oarg{UsedByAndOn} adds the message
%   \begin{quote}
%       \emph{(Used by \meta{list of theorem-like destination(s)} on page(s) \meta{list of page(s)}.)}
%   \end{quote}
%   Each text is followed by a line break
%   and is set after the original location of the referenced label \meta{LabelName}.
%   If \pkg{hyperref} has been loaded, there will also be hyperlinks to the destinations.
%   \end{variable}
%
%   For example, suppose we have the following lemma.
%	\begin{lemma}	\label{lemma:SmoothFunction}
%	    Any smooth function $f\colon \mathbb{R}\to \mathbb{R}$ is continuous.
%	\end{lemma}
%   And we will use it in the proof of the following result.
%	\begin{corollary}	\label{cor:DerivativeContinuous}
%	    Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth.
%	    The derivative $f^{\prime}\colon \mathbb{R}\to \mathbb{R}$ is continuous.
%   \begin{proof}
%       The derivative of a smooth map is itself smooth.
%       Hence, the claim follows by \cref[UsedBy]{lemma:SmoothFunction}.
%   \end{proof}
%	\end{corollary}
%   The previous result will in turn be used in the proof of the next one.
%	\begin{corollary}	\label{cor:AllDerivativesContinuous}
%	    Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth and $k\in\mathbb{N}$.
%	    The $k$th derivative $f^{(k)}\colon \mathbb{R}\to \mathbb{R}$ is continuous.
%   \begin{proof}
%       This follows from \cref[UsedByAndOn]{cor:DerivativeContinuous} by induction.
%   \end{proof}
%	\end{corollary}
%   The code for the above examples is as follows:
%	\begin{quote}
%	\begin{verbatim}
%	\begin{lemma}	\label{lemma:SmoothFunction}
%	    Any smooth function $f\colon \mathbb{R}\to \mathbb{R}$
%	    is continuous.
%	\end{lemma}
%
%	\begin{corollary}   \label{cor:DerivativeContinuous}
%	    Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth.
%	    The derivative $f^{\prime}\colon \mathbb{R}\to \mathbb{R}$
%	    is continuous.
%	\begin{proof}
%	    The derivative of a smooth map is itself smooth.
%	    Hence, the claim follows by \cref[UsedBy]{lemma:SmoothFunction}.
%	\end{proof}
%	\end{corollary}
%
%	\begin{corollary}   \label{cor:AllDerivativesContinuous}
%	    Suppose $f\colon \mathbb{R}\to \mathbb{R}$ is smooth and
%	    $k\in\mathbb{N}$. The $k$th derivative
%	    $f^{(k)}\colon \mathbb{R}\to \mathbb{R}$
%	    is continuous.
%	\begin{proof}
%	    This follows from
%	    \cref[UsedByAndOn]{cor:DerivativeContinuous} by induction.
%	\end{proof}
%	\end{corollary}
%	\end{verbatim}
%	\end{quote}
%   Unfortunately, due to how this package is currently implemented, to get these
%   experimental options to work it is necessary to abuse the usage of proof environments.
%   Namely, one needs to nest the proof environment \emph{inside} the theorem-like environment.
%   Note carefully how the proof environments are (ab)used in the above code example.
%
%   This is -- as far is I know -- not how these environments are supposed to be used.
%   In particular, placing text between theorem-like environment and the corresponding proof,
%   as is often common, will result in a wrong reference. Namely, instead of referencing the
%   theorem-like environment by name only the corresponding section name would be printed, e.g.
%   \enquote{\emph{Used by \cref{sec:UsedByAndOn}.}}.
%   You can see this for yourself, if you move the proof environment out of the theorem-like
%   environment in the above examples.
%   Hence, using proof environments correctly results in messages which are less helpful to the reader.
%   On the other hand, using this experimental functionality to help the reader forces users (i.e. authors)
%   of this package to use proof environments incorrectly.
%   This sounds like a No-Free-Lunch theorem...
%   Therefore, use these two experimental options at your own discretion!
%
%
%	\section{Hints and tips}
%	\label{sec:tips}
%
%	If you use the |capitalise| option for \pkg{cleveref}, you might want
%	to revert this capitalisation for page references for more visual appeal by putting
%	\begin{quote}
%		|\crefname{page}{page}{pages}|
%	\end{quote}
%	in your document's preamble, after loading \pkg{cleveref-usedon}.
%
%	It is recommended to not use the optional arguments for equation-like
%	environments such as \cref[UsedOn]{eq:Stokes} because sometimes\footnote{I haven't quite tracked down this bug.}
%   the info message will --- unhelpfully --- be printed inside the equation
%	environment, like so (this might or might not\footnote{
%   In version 0.2.0 of this package, the text \enquote{\emph{Used on page 2.}}
%   was printed right after the formula in the equation environment.}
%   show undesired behaviour):
%	\begin{equation}
%		\int_{M}\mathrm{d}\omega	=\int_{\partial M}\omega.	\label{eq:Stokes}
%	\end{equation}
%	So, one should use this functionality only for theorem-like
%	environments such as theorems, lemmas and exercises etc.
%
%   If one references the same label multiple times but with different options, say |UsedOn| and |UsedBy|,
%   then \emph{both} info messages are printed after the original label location.
%   This is not how this functionality was intended and you shouldn't use it like that.
%   I am not going to implement a check which various combinations of these options are used for the same label.
%
%	\subsection{Editing the info messages}
%	\label{subsec:EditInfoMsg}
%
%	\begin{function}{\UsedOnMessage, \UsedByMessage, \UsedByAndOnMessage}
%      \begin{syntax}
%           \cs{UsedOnMessage}\marg{PageList from cpageref}
%           \cs{UsedByMessage}\marg{EnvironmentList from cpageref}
%           \cs{UsedByAndOnMessage}\marg{EnvironmentList from cpageref}\marg{PageList from cpageref}{}
%       \end{syntax}
%	The standard messages which get printed to the first line of the labelled
%	environment are
%   \begin{quote}
%       \emph{(Used on \meta{PageList}.)},   \newline
%       \emph{(Used by \meta{EnvironmentList}.)},    \newline
%       \emph{(Used by \meta{EnvironmentList}) on \meta{PageList}.)},
%   \end{quote}
%   respectively
%   --- followed by a line break --- where \meta{PageList} is generated internally
%	by \pkg{cleveref} via |\cpageref| and \meta{EnvironmentList} is generated internally
%	by \pkg{cleveref} via |\cref|.
%	You can change these behaviours by redefining the macros |\UsedOnMessage|, |\UsedByMessage|
%   and |\UsedByAndOnMessage|, e.g. as
%	\begin{quote}
%	\begin{verbatim}
%   \RenewDocumentCommand{\UsedOnMessage}{ m }{
%       \emph{(Will be cited on #1.)} \newline
%   }
%   \RenewDocumentCommand{\UsedByMessage}{ m }{
%       \emph{(Will be applied in #1.)} \newline
%   }
%   \RenewDocumentCommand{\UsedByAndOnMessage}{ m m }{
%       \emph{(Will be applied in #1 on #2.)} \newline
%   }
%	\end{verbatim}
%	\end{quote}
%	\end{function}
%
%
%	\section{Interaction with other packages}
%	\label{sec:OtherPackages}
%
%	All interactions with other packages mentioned in Section 13 of
%	\pkg{cleveref}'s documentation also apply to \pkg{cleveref-usedon}.
%	In fact (if \pkg{cleveref-usedon} is loaded last),
%	\pkg{ntheorem}'s |\thref| and
%	\pkg{varioref}'s |\vref| also obtain the additional |UsedOn|
%	functionality because \pkg{cleveref} redefines these macros to
%	be aliases for |\cref|. Of course, they need to be loaded in the correct order, i.e.
%   \begin{verbatim}
%   \usepackage{ntheorem}
%   \usepackage{hyperref}
%   \usepackage{cleveref-usedon}
%   \end{verbatim}
%   or
%   \begin{verbatim}
%   \usepackage{varioref}
%   \usepackage{hyperref}
%   \usepackage{cleveref-usedon}
%   \end{verbatim}
%
%
%	\section{Future features}
%	\label{sec:future}
%
%   For all feature requests, either
%   \href{https://github.com/SvenPistre/cleveref-usedon/issues}{create a github issue} or
%   \href{mailto:cleveref-usedon@sven-pistre.com?subject=[cleveref-usedon]}{send me an email}.
%
%	Let's just reference \cref[UsedOn]{thm:SqrtTwoIrrational} one last time for the fun of it,
%   check \cpageref{thm:SqrtTwoIrrational} again to see the effect to the reference list
%   in the header of \cref{thm:SqrtTwoIrrational}.
%
% \end{documentation}
%
%
% \begin{implementation}
%
%
%   \section{Implementation}
%	\label{sec:implementation}
%
%   Start the \pkg{DocStrip} guards.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%   Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
%    \begin{macrocode}
%<@@=UsedOn>
%    \end{macrocode}
%
%   If the \LaTeX{} version is too old, then abort loading and show an error message.
%   The macro |\IfFormatAtLeastTF| is not be available on \LaTeX{} versions older than |2020-10-01|
%   so we need to provide an internal workaround.
%    \begin{macrocode}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\IfFormatAtLeastTF{2021-06-01}{%
    % LaTeX2e version new enough
}{%
    \PackageError{cleveref-usedon}{%
        Mismatched~LaTeX~support~files~detected.\MessageBreak
        Your~LaTeX~format~is~dated~\fmtversion,\MessageBreak
        but~the~package~cleveref-usedon\MessageBreak
        requires~at~least~2021-06-01.\MessageBreak
        Update~your~TeX~distribution.\MessageBreak
        \MessageBreak
        Loading~cleveref-usedon~will~abort!}%
        {Update~your~TeX~distribution~using~your~TeX~package~manager.}%
}
%    \end{macrocode}
%
%   If the version of the \LaTeX3 kernel is too old, then abort loading and show an error message.
%   The macro |\IfExplAtLeastTF| currently does not exist at all\footnote{
%   But might in the future, see \href{https://github.com/latex3/latex2e/issues/1004}{github issue \#1004}.},
%   but we can provide an internal workaround.
%    \begin{macrocode}
\providecommand\IfExplAtLeastTF{\@ifl@t@r\ExplLoaderFileDate}
\RequirePackage{expl3}[2021-05-16]
\IfExplAtLeastTF{2021-05-16}{%
    % expl3 version new enough
}{%
    \PackageError{cleveref-usedon}{%
        Support~package~expl3~too~old.\MessageBreak
        The~L3~programming~layer~in~the~LaTeX~format\MessageBreak
        is~dated~\ExplLoaderFileDate,\MessageBreak
        but~the~package~cleveref-usedon\MessageBreak
        requires~at~least~2021-05-16.\MessageBreak
        Update~your~TeX~distribution.\MessageBreak
        \MessageBreak
        Loading~cleveref-usedon~will~abort!}%
        {Update~your~TeX~distribution~using~your~TeX~package~manager.}%
}
%    \end{macrocode}
%
%   \subsection{Options and requirements}
%
%	The following package is included in the \LaTeX{} kernel since 2020-10-01.
%   Here, it is manually |\Require|'d for users with older \LaTeX{} versions.
%   For such users the loading should have been aborted anyway.
%    \begin{macrocode}
\RequirePackage{xparse}
%    \end{macrocode}
%
%	The following package options currently don't do anything.
%    \begin{macrocode}
\bool_new:N \g_@@_StandardBehaviour_bool
\bool_gset_true:N \g_@@_StandardBehaviour_bool
\DeclareOption{usedon}{
    \OptionNotUsed
    \bool_gset_true:N \g_@@_StandardBehaviour_bool
}
\DeclareOption{notusedon}{
    \OptionNotUsed
    \bool_gset_false:N \g_@@_StandardBehaviour_bool
}
%    \end{macrocode}
%
%	All other package options get passed on to \pkg{cleveref} which is the base for the current package here.
%    \begin{macrocode}
\DeclareOption*{
    \PackageInfo{cleveref-usedon}
        {Passing~option~'\CurrentOption'~to~cleveref}
    \PassOptionsToPackage{\CurrentOption}{cleveref}
}
\ProcessOptions*
\RequirePackage{cleveref}[2018/03/27]
%    \end{macrocode}
%
%   \subsection{Patches of known bugs to \pkg{cleveref}}
%
%	The following fixes the range bug for |\cpageref| in \pkg{cleveref v0.21.4}.
%	See \url{https://tex.stackexchange.com/a/620066/267438}.
%   (We need to temporarily reset the \pkg{DocStrip} guards.)
%
%    \begin{macrocode}
%<@@=>
\newcommand*{\@setcpagerefrange}[3]{%
    \@@setcpagerefrange{#1}{#2}{cref}{#3}}
\newcommand*{\@setCpagerefrange}[3]{%
    \@@setcpagerefrange{#1}{#2}{Cref}{#3}}
\newcommand*{\@setlabelcpagerefrange}[3]{%
    \@@setcpagerefrange{#1}{#2}{labelcref}{#3}}
%<@@=UsedOn>
%    \end{macrocode}
%
%   \subsection{Overloading of label and cref}
%
%	We need variants of |\str_case:nn|
%	which expand the input string token.
%   This will be used to match
%	options for \cs{@@_Processor}.
%
%    \begin{macrocode}
\prg_generate_conditional_variant:Nnn \str_case:nn { x } { TF }
\cs_generate_variant:Nn \str_case:nn { x }
%    \end{macrocode}
%
%\begin{variable}{\g_@@_k_seq}
%	Let's initialise a global key sequence for those label names that
%	have been referenced via |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|.
%
%    \begin{macrocode}
\seq_new:N \g_@@_k_seq
%    \end{macrocode}
%\end{variable}
%
%\begin{variable}{\g_@@_kv_prop}
%	And we'll also create a global key-value property list with
%	label names as keys and the maximal amount of times they have
%	been referenced via |[UsedOn]| as values (possibly known from
%	the last pdflatex run).
%
%    \begin{macrocode}
\prop_new:N \g_@@_kv_prop
%    \end{macrocode}
%\end{variable}
%
%
%\begin{variable}{\g_@@_Options_clist}
%	This |clist| contains all options that can be passed to |\cref| which are currently implemented.
%    \begin{macrocode}
\clist_new:N \g_@@_Options_clist
\clist_set:Nn \g_@@_Options_clist {UsedOn, UsedBy, UsedByAndOn}
%    \end{macrocode}
%\end{variable}
%
%\begin{macro}{\UsedOnMessage}
%	The following are the standard texts that get printed in the first line
%	of the labelled environment which later gets referenced with
%   |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|.
%
%    \begin{macrocode}
\NewDocumentCommand{\UsedOnMessage}{m}{
    \emph{(Used~on~#1.)} \newline
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\UsedByMessage}
%    \begin{macrocode}
\NewDocumentCommand{\UsedByMessage}{ m }{
    \emph{(Used~by~#1.)} \newline
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\UsedByAndOnMessage}
%    \begin{macrocode}
\NewDocumentCommand{\UsedByAndOnMessage}{ m m }{
    \emph{(Used~by~#1~on~#2.)} \newline
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_Printer}
%	Given a \meta{LabelName}, the following command records all references
%	via the optional |cref| arguments |[UsedOn]|, |[UsedBy]| or |[UsedByAndOn]|, i.e.
%   when the user called |\cref|\oarg{Option}\marg{LabelName}.
%   They are recorded in a temporary comma-separated list
%	(a |clist| in |expl3| speak). This |clist| is then passed to \pkg{cleveref}'s
%   |cpageref| or |cref| which in turn is passed to |\UsedOnMessage|, |\UsedByMessage|
%   or |\UsedByAndOnMessage| to be printed after the original label.
%
%    \begin{macrocode}
\NewDocumentCommand{\@@_Printer}{ m m }{%
%    \end{macrocode}
%	First, we will check if the reference \meta{Option}|@|\meta{LabelName}|@1|
%	exists. Here, the |@1| means that \meta{LabelName} has been referenced
%	with option \oarg{Option} at least once. If this reference does not exist,
%	nothing happens.
%\iffalse
%%    % Check if the reference #1@<LabelName>@1 exists
%%    % Here the @1 means that <LabelName> has been referenced
%%    % with option #1 at least once where #1 is
%%    % 'UsedOn', 'UsedBy' or 'UsedByAndOn'
%\fi
%    \begin{macrocode}
    \cs_if_exist:cT {r@#1@#2@1}
    {
%    \end{macrocode}
%	Next, we store all the references of the form
%	\meta{Option}|@|\meta{LabelName}|@|\meta{Number} in a temporary
%	comma-separated list (|clist|). We do this by looping from 1 to the value
%	of |LastRun@|\meta{Option}|@|\meta{LabelName} (if the latter value exists,
%	otherwise we set it to 1). Initially, this will need two consecutive runs of pdflatex.
%\iffalse
%%        % In a tmp clist we store all the references of the form
%%        %    `<Option>@<LabelName>@<Number>`
%%        % where Number between 1 and \value{LastRun@UsedOn@<LabelName>}
%%        % if the latter exists, otherwise until 1
%%        % Should/will normally need two consecutive runs of pdflatex
%\fi
%    \begin{macrocode}
        \cs_if_free:cTF {c@LastRun@#1@#2}
            { \int_set:Nn \l_tmpa_int { 1 } }
            { \int_set:Nn \l_tmpa_int { \value{LastRun@#1@#2} } }
        \int_set:Nn \l_tmpb_int { 1 }
        \int_while_do:nn { \l_tmpb_int <= \l_tmpa_int }
        {
            \clist_put_right:Nx \l_tmpa_clist { #1@#2@\int_use:N \l_tmpb_int }
            \int_incr:N \l_tmpb_int
        }
%    \end{macrocode}
%	Finally, we print the message that was set in the macro |\UsedOnMessage|.
%\iffalse
%%        % Print `UsedOn` message by calling \cpageref with the parameter clist above
%%        % Uncomment the next two lines for debugging to see the contents of \l_tmpa_clist
%%        %%   Arguments~of~cpageref/cref~are:
%%        %%   \par\clist_use:Nn \l_tmpa_clist {\par}\par
%\fi
%    \begin{macrocode}
        \str_case:xn { \str_foldcase:n { #1 } }
        {
            {usedon}
                {\UsedOnMessage{\cpageref{\l_tmpa_clist}}}
            {usedby}
                {\UsedByMessage{\cref{\l_tmpa_clist}}}
            {usedbyandon}
                {\UsedByAndOnMessage{\cref{\l_tmpa_clist}}
                    {\cpageref{\l_tmpa_clist}}}
        }
    }
}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_PrintMessage}
%	This macro prints the corresponding |UsedOn| message after the original label.
%    \begin{macrocode}
\NewDocumentCommand{\@@_PrintMessage}{ m }{%
    \clist_map_inline:Nn \g_@@_Options_clist
        { \@@_Printer{##1}{#1} }
}%
%    \end{macrocode}
%\end{macro}
%
%
%\begin{variable}{\l_@@_Option_str}
%	This variable will be used to store the used option in a |\cref| call.
%
%    \begin{macrocode}
\str_new:N \l_@@_Option_str
%    \end{macrocode}
%\end{variable}
%
%\begin{macro}{\@@_Processor}
%	This macro takes an optional argument
%	(a case-insensitive version of the options or their shortform)
%	and a mandatory argument (a single \marg{LabelName} or a |clist| \{\meta{LabelName1},\meta{LabelName2},\ldots\}).
%    \begin{macrocode}
\NewDocumentCommand{\@@_Processor}{ o m }{%
    \IfValueT{#1}{
%    \end{macrocode}
%	First, we check if the option |[UsedOn]| or |[uo]| (case-insensitive) was used.
%    \begin{macrocode}
        \str_case:xnTF { \str_foldcase:n { #1 } }
        {
%    \end{macrocode}
%\iffalse
%%            % check if options 'UsedOn', 'UsedBy' or 'UsedByAndOn'
%%            % (case-insensitive) were used in one of the following forms
%\fi
%    \begin{macrocode}
            {usedon} {\str_set:Nn \l_@@_Option_str {UsedOn}}
            {uo}     {\str_set:Nn \l_@@_Option_str {UsedOn}}
            {usedby} {\str_set:Nn \l_@@_Option_str {UsedBy}}
            {ub}     {\str_set:Nn \l_@@_Option_str {UsedBy}}
            {usedbyandon} {\str_set:Nn \l_@@_Option_str {UsedByAndOn}}
            {ubao}        {\str_set:Nn \l_@@_Option_str {UsedByAndOn}}
        }
        {
            {
%    \end{macrocode}
%	Loop through the (potential) label list in the mandatory argument
%	of |\cref| (or |\Cref|) which gets passed as the mandatory argument
%	of the current macro.
%\iffalse
%%                % Loop through (potential) label list in arg of \cref (or \Cref)
%\fi
%    \begin{macrocode}
                \seq_set_from_clist:Nn \l_tmpa_seq {#2}
                \seq_map_inline:Nn \l_tmpa_seq
                {
%    \end{macrocode}
%	If the label has \emph{not} been referenced yet via the option |#1| where |#1| is one of
%   the current available options in \ExplSyntaxOn   \{\g__UsedOn_Options_clist\}  \ExplSyntaxOff
%   , create a
%	counter for the current run |ThisRun@<Option>@##1|.
%	If we are not in the initial run anymore, there should be a counter
%	|LastRun@<Option>@##1| which contains the maximal amount this
%	specific label has been referenced via |UsedOn|.
%	If we are in the initial run, we need to create this counter as well.
%	Then save the label in the global container \cs{g_@@_k_seq}.
%\iffalse
%%                    % if the label has not been referenced yet,
%%                    % create a counter for the current and last run and save the label in the
%%                    % global container \g_@@_k_seq
%\fi
%    \begin{macrocode}
                    \seq_if_in:NxF \g_@@_k_seq
                        { \l_@@_Option_str @##1}
                    {
                        \newcounter{
                            ThisRun@ \l_@@_Option_str @##1
                        }
                        \cs_if_free:cT {c@LastRun@ \l_@@_Option_str @##1}
                            {
                            \newcounter{LastRun@ \l_@@_Option_str @##1}
                            }
                        \seq_gput_right:Nx \g_@@_k_seq
                            { \l_@@_Option_str @##1}
                    }
%    \end{macrocode}
%	Increase the counter for the current run by 1 and set the counter
%	for last run (containing the maximal amount of |UsedOn|-|\cref|'s)
%	to...the maximal amount of |UsedOn|-|\cref|'s.
%\iffalse
%%                    % increase the counters and compare with max counter
%\fi
%    \begin{macrocode}
                    \stepcounter{ThisRun@ \l_@@_Option_str @##1}
                    \setcounter{LastRun@ \l_@@_Option_str @##1}{%
                        \fp_eval:n
                            { max(%
                            \value{ThisRun@ \l_@@_Option_str @##1},%
                            \value{LastRun@ \l_@@_Option_str @##1}
                            ) }%
                    }
%    \end{macrocode}
%	Store the value of the max counter |LastRun@<Option>@##1| in
%	the global container \cs{g_@@_kv_prop}.
%\iffalse
%%                    % store the value in global key-value property list
%\fi
%    \begin{macrocode}
                    \prop_gput:Nxx \g_@@_kv_prop
                        { \l_@@_Option_str @##1}
                        {\arabic{LastRun@ \l_@@_Option_str @##1}}
%    \end{macrocode}
%	Now we create a numbered auxiliary label. This label is issued at the
%	location where we referenced the original label via
%	|\cref[UsedOn]|\meta{LabelName}.
%	The new auxiliary label has the prefix |UsedOn@|, |UsedBy@| or |UsedByAndOn@| and
%	the suffix |@\arabic{ThisRun@<Option>@##1}|, e.g.
%	|UsedOn@thm:Pythagoras@4| if it is the fourth time that we called \newline
%	|\cref[UsedOn]{thm:Pythagoras}|.
%\iffalse
%%                    % create a label for the UsedOn reference and number this label
%\fi
%    \begin{macrocode}
                    \@@_origlabel{
                        \l_@@_Option_str @##1@
                        \arabic{ThisRun@ \l_@@_Option_str @##1}
                    }
                }
            }
        }
        {
%    \end{macrocode}
%	Throw an error, if an unrecognised option was used for the
%	optional argument to this macro.
%\iffalse
%%                    % Throw an error, if an unrecognised option was used
%%                    % for the optional argument to this macro.
%\fi
%    \begin{macrocode}
            \msg_new:nnn {cleveref-usedon} { OptionSpellingError }
                {   \MessageBreak
                    Spelling~error~\msg_line_context:
                    \MessageBreak
                    Did~you~mean~to~pass~option\MessageBreak
                    'UsedOn'~to~cref~or~Cref?
                }
            \msg_fatal:nn { cleveref-usedon } { OptionSpellingError }
        }
    }
}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_cref}
%	This is just a wrapper around \pkg{cleveref}'s |\cref|.
%	Additionally the \cs{@@_Processor} gets called.
%    \begin{macrocode}
\NewDocumentCommand{\@@_cref}{ s o m }{%
    \IfBooleanTF{#1}{ \@@_origcref*{#3} }{ \@@_origcref{#3} }%
    \@@_Processor[#2]{#3}
}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_Cref}
%	This is just a wrapper around \pkg{cleveref}'s |\Cref|.
%	Additionally the \cs{@@_Processor} gets called.
%    \begin{macrocode}
\NewDocumentCommand{\@@_Cref}{ s o m }{%
    \IfBooleanTF{#1}{ \@@_origCref*{#3} }{ \@@_origCref{#3} }%
    \@@_Processor[#2]{#3}
}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_ReadFromAux}
%	From the .aux file we will read the contents of the
%	global container \cs{g_@@_kv_prop}.
%	This is a key-value property list and we create and set a
%	for each label (key) and the maximal amount (value) it was called in the last run.
%    \begin{macrocode}
\NewDocumentCommand{\@@_ReadFromAux}{ }{%
    \prop_map_inline:Nn \g_@@_kv_prop
    {
        \newcounter{LastRun@##1}
        \setcounter{LastRun@##1}{##2}
    }
}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@_WriteToAux}
%	For each label we write a line in the .aux file of the form:	\newline
%	\meta{LabelName} = \meta{Maximal references via UsedOn in last run}.\newline
%	This information can be constructed from the global container \cs{g_@@_k_seq}
%	and the counters with prefix |ThisRun@| we set earlier.
%	We need to wrap this in the on/off switch for |expl3| functionality.
%    \begin{macrocode}
\NewDocumentCommand{\@@_WriteToAux}{ }{%
%    \end{macrocode}
%%    % First, we clear the global key-value prop list \cs{g_@@_kv_prop} and
%%    % then we rebuild it with the information from the current run.
%    \begin{macrocode}
    \prop_clear:N \g_@@_kv_prop
    \seq_map_inline:Nn \g_@@_k_seq
        { \prop_gput:Nxx \g_@@_kv_prop {##1}{\arabic{ThisRun@##1}} }
%    \end{macrocode}
%\iffalse
%%    % Turn on |expl3| functionality in .aux file.
%\fi
%    \begin{macrocode}
    \iow_now:cx { @auxout }
        { \token_to_str:N \ExplSyntaxOn }
%    \end{macrocode}
%%    % Loop through the key-val |proplist| and write contents to .aux file.
%    \begin{macrocode}
    \prop_map_inline:Nn \g_@@_kv_prop
    {
        \iow_now:cx { @auxout }
            {
                \prop_gput_from_keyval:Nn \token_to_str:N \g_@@_kv_prop
                {##1=##2}
            }
    }
%    \end{macrocode}
%\iffalse
%%    % Turn off |expl3| functionality in .aux file.
%\fi
%    \begin{macrocode}
    \iow_now:cx { @auxout }
        { \token_to_str:N \ExplSyntaxOff }
}%
%    \end{macrocode}
%\end{macro}
%
%	At the hook |\AtBeginDocument| we read from the .aux file
%	and patch commands.
%    \begin{macrocode}
\AtBeginDocument{%
    \@@_ReadFromAux
%    \end{macrocode}
%	Patch label and cref to include the new |[UsedOn]| capabilities.
%    \begin{macrocode}
    \NewCommandCopy{\@@_origlabel}{\label}
    \NewCommandCopy{\@@_origcref}{\cref}
    \NewCommandCopy{\@@_origCref}{\Cref}
    \RenewDocumentCommand{\label}{ m }{%
        \@@_origlabel{#1}\@@_PrintMessage{#1}
    }%
    \RenewCommandCopy{\cref}{\@@_cref}
    \RenewCommandCopy{\Cref}{\@@_Cref}
}%
%    \end{macrocode}
%
%	At the hook |\AtEndDocument| we write to the .aux file.
%    \begin{macrocode}
\AtEndDocument{%
    \@@_WriteToAux
}%
%    \end{macrocode}
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintChanges
% \PrintIndex