summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cleveref-usedon
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-04-13 03:01:11 +0000
committerNorbert Preining <norbert@preining.info>2023-04-13 03:01:11 +0000
commitc6d2f94d04f69bb5b2143ef62e7ab90bd3b60212 (patch)
treebddc530efd786986da5407c2e808a1d73c728ede /macros/latex/contrib/cleveref-usedon
parent45c7bac9080d91b53c686e776fc6217d7f139b86 (diff)
CTAN sync 202304130300
Diffstat (limited to 'macros/latex/contrib/cleveref-usedon')
-rw-r--r--macros/latex/contrib/cleveref-usedon/README.md55
-rw-r--r--macros/latex/contrib/cleveref-usedon/cleveref-usedon.dtx643
-rw-r--r--macros/latex/contrib/cleveref-usedon/cleveref-usedon.ins76
-rw-r--r--macros/latex/contrib/cleveref-usedon/cleveref-usedon.pdfbin0 -> 318914 bytes
4 files changed, 774 insertions, 0 deletions
diff --git a/macros/latex/contrib/cleveref-usedon/README.md b/macros/latex/contrib/cleveref-usedon/README.md
new file mode 100644
index 0000000000..1672a6eab1
--- /dev/null
+++ b/macros/latex/contrib/cleveref-usedon/README.md
@@ -0,0 +1,55 @@
+## The *cleveref-usedon* package
+Patches the cleveref package and adds forward-referencing functionality
+
+## Description
+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 **where** is this result used later on in this long text? I
+really would find that helpful to decide **why** I should read the
+proof."*
+
+You can, of course, use the PDF search function of your viewer to
+look up the string *"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 **cleveref-usedon** tries to address.
+The info message *"Used on p. 40, 43-45 and 101."* would then be
+printed to the header of Lemma 1.12.
+
+Check the [package documentation](./cleveref-usedon.pdf) for more info on the usage or look at an [example](https://github.com/SvenPistre/cleveref-usedon/tree/main/examples) directly.
+
+## Installation
+Place the file ``cleveref-usedon.sty`` at a location which your LaTeX distribution understands. For instance, on OS X you can place it in ``~/Library/texmf/tex/latex``.
+If you don't know where that would be on your OS, you can also simply drop this file in the same directory as the ``.tex`` file where you want to use the package.
+
+If you wish you can also 'compile' the package style file ``cleveref-usedon.sty`` and the documentation ``cleveref-usedon.pdf`` 'from source' as follows:
+- To generate the package style file, run the installation file ``cleveref-usedon.ins`` through pdflatex.
+- To generate the documentation, run the DocStrip file ``cleveref-usedon.dtx`` through pdflatex.
+
+---
+Copyright (C) 2023 Sven Pistre
+
+E-mail: [cleveref-usedon@sven-pistre.com](mailto:cleveref-usedon@sven-pistre.com?subject=[[cleveref-usedon]])
+```
+Files:
+cleveref.ins Batch file, run through LaTeX
+cleveref.dtx Docstrip archive, run through LaTeX
+cleveref.sty LaTeX package, generated by cleveref.ins from cleveref.dtx
+cleveref.pdf Package documentation, generated from cleveref.dtx
+README This file
+
+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.
+```
+--- \ No newline at end of file
diff --git a/macros/latex/contrib/cleveref-usedon/cleveref-usedon.dtx b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.dtx
new file mode 100644
index 0000000000..ff7d07f21f
--- /dev/null
+++ b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.dtx
@@ -0,0 +1,643 @@
+\def\packageversion{0.2.0}
+\def\packagedate{2023-04-07}
+% \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.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{cleveref-usedon.dtx}
+%</driver>
+%
+%<package>\NeedsTeXFormat{LaTeX2e}[2022/06/01]
+%<package>\RequirePackage{expl3}
+%<package>\ProvidesExplPackage{cleveref-usedon}
+%<package> {\packagedate}
+%<package> {\packageversion}
+%<package> {Patches the cleveref package and adds forward-referencing functionality}
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{thmtools}
+\usepackage{hyperref}
+\usepackage[capitalise]{cleveref-usedon}[2023/03/29]
+\declaretheorem[
+ numberwithin=section,
+ name=Theorem]{theorem}
+\crefname{page}{page}{pages} % do NOT capitalise pages for more visual appeal
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{\jobname.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{160}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+% \DoNotIndex{\newcommand,\newenvironment}
+%
+% \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{@}-guards to the macros \texttt{\textbackslash{}origlabel},%
+% \texttt{\textbackslash{}origcref}, and \texttt{\textbackslash{}origCref} to prevent them from leaking.%
+% }
+%
+% \GetFileInfo{cleveref-usedon.dtx}
+% \title{The \pkg{cleveref-usedon} package%
+% \thanks{This document corresponds to
+% \pkg{cleveref-usedon}~v\packageversion,
+% dated~\packagedate.}}
+% \author{Sven Pistre%
+% \thanks{
+% \href{mailto:cleveref-usedon@sven-pistre.com?subject=[cleveref-usedon]}{cleveref-usedon@sven-pistre.com}}
+% }
+% \date{\packagedate}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package adds ``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
+% ``\emph{Used on pages \meta{pagerange}.}''.
+% 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}
+%
+% \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 ``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 ``\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.
+% \clearpage
+% Let's clear the page of this PDF, so that we can see the effects of
+% referencing \cref{thm:SqrtTwoIrrational} without the optional argument
+% |[UsedOn]|, i.e.
+% \begin{quote}
+% |\cref{thm:SqrtTwoIrrational}|.
+% \end{quote}
+% 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: \\
+% 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}. \\
+%
+% \DescribeMacro{\cref}
+% \DescribeMacro{\Cref}
+% |\cref|\oarg{UsedOn}\marg{LabelName} \\
+% The |\cref| macro can be called with option |UsedOn| or the short form
+% |uo|. This is case-insensitive, i.e. you could also write
+% \begin{quote}
+% |\cref[UsEdOn]|\marg{LabelName} \\
+% |\cref[uO]|\marg{LabelName}
+% \end{quote}
+% --- but why would you?
+%
+% This additional option adds the text ``\emph{(Used on page(s) ... .)}''
+% with an additional line break right after where the label has been originally
+% set. If \pkg{hyperref} has been loaded, there will also be hyperlinks
+% to the corresponding pages from where the label has been referenced.
+%
+% If the original label has been set in a theorem-style 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-style
+% environment. The same functionality can be used for |\Cref|.
+%
+% The package \pkg{cleveref-usedon} is implemented using |expl3|.
+% If you are interested, I have spent some time to document and comment
+% on the implementation in \cref{sec:implementation}.
+%
+% \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 argument for equation-style
+% environments such as \cref[UsedOn]{eq:Stokes} because otherwise the
+% info message will --- unhelpfully --- be printed inside the equation
+% environment, like so:
+% \begin{equation}
+% \int_{M}\mathrm{d}\omega =\int_{\partial M}\omega. \label{eq:Stokes}
+% \end{equation}
+% So, for now, one should use this functionality only for theorem-style
+% environments such as theorems, lemmas and maybe exercises.
+%
+% \subsection{Editing the info message}
+% \label{subsec:edit_info_msg}
+% \DescribeMacro{\UsedOnMessage}
+% |\UsedOnMessage|\marg{PageNumberList from cpageref} \\
+% The standard message which gets printed to the first line of the labelled
+% environment is ``\textit{(Used on \meta{PageNumberList}).}'' --- followed by
+% a line break --- where \meta{PageNumberList} is generated automatically
+% by \pkg{cleveref} via |\cpageref|.
+% You can change this behaviour by redefining the macro |\UsedOnMessage|, e.g. as
+% \begin{quote}
+% \begin{verbatim}
+% \RenewDocumentCommand{\UsedOnMessage}{m}{
+% \emph{(Will be cited on #1.)} \\
+% }
+% \end{verbatim}
+% \end{quote}
+%
+% \section{Interaction with other packages}
+% \label{sec:other_packages}
+% 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|.
+%
+% \section{Future features}
+% \label{sec:future}
+% It is planned to include a package option that turns on the |UsedOn|
+% option for \emph{all} |\cref|'s calls. Additionally, a switch package option
+% might be included which reverses the standard behaviour, i.e. if one does
+% not want to use |UsedOn| functionality one needs to explicitly use
+% |\cref[NotUsedOn]|\marg{LabelName}. \\
+% 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}.
+%
+% \StopEventually{}
+%
+% \section{Implementation}
+% \label{sec:implementation}
+%
+% \iffalse
+%<*package>
+% \fi
+%
+% \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.
+% Those users will get a package warning in the .log file.
+% \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}.
+% \begin{macrocode}
+\DeclareOption*{
+ \PackageInfo{cleveref-usedon}
+ {Passing~to~cleveref:~Option~`\CurrentOption'}
+ \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} \par
+% See \url{https://tex.stackexchange.com/a/620066/267438}
+%
+% \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}}
+% \end{macrocode}
+%
+% \subsection{Overloading of label and cref}
+%
+% We need a branching variant of |\str_case:nn|
+% which expands the input string token. This will be used to match
+% options for the |\__UsedOn_Processor|.
+%
+% \begin{macrocode}
+\prg_generate_conditional_variant:Nnn \str_case:nn { x } { TF }
+% \end{macrocode}
+%
+%\begin{macro}{\g__UsedOn_k_seq}
+% Let's initialise a global key sequence for those label names that
+% have been referenced via |[UsedOn]|.
+%
+% \begin{macrocode}
+\seq_new:N \g__UsedOn_k_seq
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\g__UsedOn_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__UsedOn_kv_prop
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\UsedOnMessage}
+% The following is the standard text that gets printed in the first line
+% of the labelled environment which later gets referenced with |[UsedOn]|.
+%
+% \begin{macrocode}
+\NewDocumentCommand{\UsedOnMessage}{m}{
+ \emph{(Used~on~#1.)} \\
+}
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_PrintUsedOnLabel}
+% Given a \meta{LabelName}, the following command records all references
+% via |[UsedOn]| of this label in a temporary comma-separated list
+% (a |clist| in |expl3| speak). This |clist| is then passed to \pkg{cleveref}'s |cpageref|
+% and which in turn is passed to |\UsedOnMessage| to be printed after
+% the original label.
+%
+% \begin{macrocode}
+\NewDocumentCommand{\__UsedOn_PrintUsedOnLabel}{ m }{%
+% \end{macrocode}
+% First, we will check if the reference |UsedOn@|\meta{LabelName}|@1|
+% exists. Here, the |@1| means that \meta{LabelName} has been referenced
+% with option |[UsedOn]| at least once. If this reference does not exist,
+% nothing happens.
+%\iffalse
+%% % Check if the reference UsedOn@<LabelName>@1 exists
+%% % Here the @1 means that <LabelName> has been referenced
+%% % with option `UsedOn' at least once
+%\fi
+% \begin{macrocode}
+ \cs_if_exist:cT {r@UsedOn@#1@1}
+ {
+% \end{macrocode}
+% Next, we store all the references of the form
+% |UsedOn@|\meta{LabelName}|@|\meta{Number} in a temporary
+% comma-separated list (|clist|). We do this by looping from 1 to the value
+% of |LastRun@UsedOn@|\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
+%% % `UsedOn@<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@UsedOn@#1}
+ { \int_set:Nn \l_tmpa_int { 1 } }
+ { \int_set:Nn \l_tmpa_int { \value{LastRun@UsedOn@#1} } }
+ \int_set:Nn \l_tmpb_int { 1 }
+ \int_while_do:nn { \l_tmpb_int <= \l_tmpa_int }
+ {
+ \clist_put_right:Nx \l_tmpa_clist { UsedOn@#1@\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 to see the contents of \l_tmpa_clist
+%% %% Arguments~of~cpageref~are:
+%% %% \par\clist_use:Nn \l_tmpa_clist {\par}\par
+%\fi
+% \begin{macrocode}
+ \UsedOnMessage{\cpageref{\l_tmpa_clist}}
+ }
+}%
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_Processor}
+% This macro takes an optional argument
+% (a case-insensitive version of |[UsedOn]| or the shortform |[uo]|)
+% and a mandatory argument (a single \marg{LabelName} or a |clist| \{\meta{LabelName1},\meta{LabelName2},\ldots\}).
+% \begin{macrocode}
+\NewDocumentCommand{\__UsedOn_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 option 'UsedOn' (case-insensitive) was used
+%% % in one of the following forms
+%\fi
+% \begin{macrocode}
+ {usedon} {}
+ {uo} {}
+ }
+ {
+ {
+% \end{macrocode}
+% Loop through the (potential) label list in 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 |[UsedOn]|, create a
+% counter for the current run |ThisRun@UsedOn@##1|.
+% If we are not in the initial run anymore, there should be a counter
+% |LastRun@UsedOn@##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 |\g__UsedOn_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__UsedOn_k_seq
+%\fi
+% \begin{macrocode}
+ \seq_if_in:NxF \g__UsedOn_k_seq {UsedOn@##1}
+ {
+ \newcounter{ThisRun@UsedOn@##1}
+ \cs_if_free:cT {c@LastRun@UsedOn@##1}
+ { \newcounter{LastRun@UsedOn@##1} }
+ \seq_gput_right:Nx \g__UsedOn_k_seq {UsedOn@##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@UsedOn@##1}
+ \setcounter{LastRun@UsedOn@##1}{%
+ \fp_eval:n { max(%
+ \value{ThisRun@UsedOn@##1},%
+ \value{LastRun@UsedOn@##1} ) }%
+ }
+% \end{macrocode}
+% Store the value of the max counter |LastRun@UsedOn@##1| in
+% the global container |\g__UsedOn_kv_prop|.
+%\iffalse
+%% % store the value in global key-value property list
+%\fi
+% \begin{macrocode}
+ \prop_gput:Nxx \g__UsedOn_kv_prop
+ {UsedOn@##1} {\arabic{LastRun@UsedOn@##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@| and
+% the suffix |@\arabic{ThisRun@UsedOn@##1}|, e.g.
+% |UsedOn@thm:Pythagoras@4| if it is the fourth time that we called \\
+% |\cref[UsedOn]{thm:Pythagoras}|.
+%\iffalse
+%% % create a label for the UsedOn reference and number this label
+%\fi
+% \begin{macrocode}
+ \__UsedOn_origlabel{UsedOn@##1@\arabic{ThisRun@UsedOn@##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 }
+ { \\
+ Spelling~error~\msg_line_context:
+ \\
+ Did~you~mean~to~pass~option\\
+ 'UsedOn'~to~cref~or~Cref?
+ }
+ \msg_fatal:nn { cleveref-usedon } { OptionSpellingError }
+ }
+ }
+}%
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_cref}
+% This is just a wrapper around \pkg{cleveref}'s |\cref|.
+% Additionally the |\__UsedOn_Processor| gets called.
+% \begin{macrocode}
+\NewDocumentCommand{\__UsedOn_cref}{ s o m }{%
+ \IfBooleanTF{#1}{ \__UsedOn_origcref*{#3} }{ \__UsedOn_origcref{#3} }%
+ \__UsedOn_Processor[#2]{#3}
+}%
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_Cref}
+% This is just a wrapper around \pkg{cleveref}'s |\Cref|.
+% Additionally the |\__UsedOn_Processor| gets called.
+% \begin{macrocode}
+\NewDocumentCommand{\__UsedOn_Cref}{ s o m }{%
+ \IfBooleanTF{#1}{ \__UsedOn_origCref*{#3} }{ \__UsedOn_origCref{#3} }%
+ \__UsedOn_Processor[#2]{#3}
+}%
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_ReadFromAux}
+% From the .aux file we will read the contents of the
+% global container |\g__UsedOn_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{\__UsedOn_ReadFromAux}{ }{%
+ \prop_map_inline:Nn \g__UsedOn_kv_prop
+ {
+ \newcounter{LastRun@##1}
+ \setcounter{LastRun@##1}{##2}
+ }
+}%
+% \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\__UsedOn_WriteToAux}
+% For each label we write a line in the .aux file of the form: \\
+% \meta{LabelName} == \meta{Maximal references via UsedOn in last run}.\\
+% This information can be constructed from the global container |\g__UsedOn_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{\__UsedOn_WriteToAux}{ }{%
+% \end{macrocode}
+%% % First, we clear the global key-value prop list |\g__UsedOn_kv_prop| and
+%% % then we rebuild it with the information from the current run.
+% \begin{macrocode}
+ \prop_clear:N \g__UsedOn_kv_prop
+ \seq_map_inline:Nn \g__UsedOn_k_seq
+ { \prop_gput:Nxx \g__UsedOn_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__UsedOn_kv_prop
+ {
+ \iow_now:cx { @auxout }
+ { \prop_gput_from_keyval:Nn \token_to_str:N \g__UsedOn_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{%
+ \__UsedOn_ReadFromAux
+% \end{macrocode}
+% Patch label and cref to include the new |[UsedOn]| capabilities.
+% \begin{macrocode}
+ \NewCommandCopy{\__UsedOn_origlabel}{\label}
+ \NewCommandCopy{\__UsedOn_origcref}{\cref}
+ \NewCommandCopy{\__UsedOn_origCref}{\Cref}
+ \RenewDocumentCommand{\label}{ m }{%
+ \__UsedOn_origlabel{#1}\__UsedOn_PrintUsedOnLabel{#1}
+ }%
+ \RenewCommandCopy{\cref}{\__UsedOn_cref}
+ \RenewCommandCopy{\Cref}{\__UsedOn_Cref}
+}%
+% \end{macrocode}
+%
+% At the hook |\AtEndDocument| we write to the .aux file.
+% \begin{macrocode}
+\AtEndDocument{%
+ \__UsedOn_WriteToAux
+}%
+% \end{macrocode}
+%
+% \iffalse
+%</package>
+% \fi
+%
+% \Finale
+\endinput \ No newline at end of file
diff --git a/macros/latex/contrib/cleveref-usedon/cleveref-usedon.ins b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.ins
new file mode 100644
index 0000000000..b6027ef334
--- /dev/null
+++ b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.ins
@@ -0,0 +1,76 @@
+%% 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.
+%%
+
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/latex/cleveref-usedon}
+
+\preamble
+
+This is a generated file.
+
+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.
+-----------------------------------------------------------------------
+
+\endpreamble
+
+\generate{\file{cleveref-usedon.sty}{\from{cleveref-usedon.dtx}{package}}}
+
+\obeyspaces
+\Msg{*************************************************************}
+\Msg{* *}
+\Msg{* To finish the installation you have to move the following *}
+\Msg{* file into a directory searched by TeX: *}
+\Msg{* *}
+\Msg{* cleveref-usedon.sty *}
+\Msg{* *}
+\Msg{* To produce the documentation run the file *}
+\Msg{* cleveref-usedon.dtx through LaTeX. *}
+\Msg{* *}
+\Msg{* Happy TeXing! *}
+\Msg{* *}
+\Msg{*************************************************************}
+
+\endbatchfile
diff --git a/macros/latex/contrib/cleveref-usedon/cleveref-usedon.pdf b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.pdf
new file mode 100644
index 0000000000..8451670a05
--- /dev/null
+++ b/macros/latex/contrib/cleveref-usedon/cleveref-usedon.pdf
Binary files differ