Feature request: Print back-references for equations

[pwintz]

Currently, the UsedBy/UsedOn/etc messages are not displayed for equations. I would like to see where equations are referenced. It is tricky, however, because we probably don't want to use the same message format when displaying it within an equation, so it would be nice to have a way to specify an alternative. Otherwise, we'd have to do something like this:

\relax\ifmmode
    \marginnote{Referenced by: #1}
\else
    \todo[%
        inline, % Display in-line instead of in the margin. 
        size=\scriptsize, 
        color=blue!40,
        backgroundcolor=white,
        textcolor=darkgray,
        bordercolor=darkgray,
        prepend, caption={Referenced by}]{% 
        \textup{#1.}%
    }%
\fi

[Jinwen-XU]

The code below is out of date. I am just keeping it here because the new version is evolved from it, and some of the previous explanations still apply.

---

The difficulty here is that \label might be redefined inside displayed equations. For example, amsmath redefines it to be \label@in@display, which only records the label text and then passes it to the original label command at the end of the equation. But I am not sure how ntheorem handles this.

That said, if you use amsmath, you may use the following modified version of cleveref-usedon.sty (at the end). With this, you may set the UsedBy text and style as:

% \usepackage{todonotes,marginnote}

\SetUsedByText
  {%
    Referenced by:#1.%
  }
\SetUsedByMessage
  {%
    \todo[%
      inline, % Display in-line instead of in the margin.
      size=\scriptsize,
      color=blue!40,
      backgroundcolor=white,
      textcolor=darkgray,
      bordercolor=darkgray,
      prepend]{%
      \textup{\UsedByText{#1}}%
    }%
  }
\SetUsedByMessageMath
  {%
    \marginnote{\UsedByText{#1}}%
  }

And similarly for UsedOn and UsedByAndOn. Then things should work as you wished.

However, since \label@in@display is specific to amsmath, without further test for other cases, I cannot yet risk to merge this version of code into the main branch for the sake of compatibility.

---

Below is the modified cleveref-usedon.sty.

(updated, please see the next comment)

[Jinwen-XU]

The code below is out of date. I am just keeping it here because the new version is evolved from it, and some of the previous explanations still apply.

---

Hopefully the following version also works for ntheorem. The code is a bit redundant though.

Without \SetUsedByMessageMath (or should I name it as \SetUsedByMathMessage?), nothing would happen for equations, as usual. The actual configuration should definitely be left to the user.

Another note is that if instead print the info on the margin one wishes to print it immediately after an equation, the following code might help:

\ExplSyntaxOn
\SetUsedByMessageMath
  {
    \tl_gset:Ne \g_tmpa_tl {\UsedByText{#1}}
  }
\AddToHook{env/equation/before}{\tl_gclear:N \g_tmpa_tl}
\AddToHook{env/equation/after}
  {
    \todo[%
      inline, % Display in-line instead of in the margin.
      size=\scriptsize,
      color=blue!40,
      backgroundcolor=white,
      textcolor=blue!50!cyan,
      bordercolor=blue!50!cyan,
      prepend]{%
      \textup{\tl_use:N \g_tmpa_tl}%
    }%
  }
\ExplSyntaxOff

Note that for some reason one has to use fully expanded version \tl_gset:Ne otherwise there would be many errors like

Argument of \@cref@stack@top has an extra }.
<inserted text> 
Paragraph ended before \@cref@stack@top was complete.
<to be read again> 
...

Thus I am not really sure if it could always work... it works in my testing document though... Also, the above code only patches equation, the same thing needs to be done for other type of displayed environments.

Below is my testing document:

\documentclass{article}

\usepackage{ntheorem}
\newtheorem{theorem}{Theorem}
\newtheorem{lemma}{Lemma}
\usepackage[usedby]{cleveref-usedon}

\usepackage{todonotes,marginnote}

\SetUsedByText
  {%
    Referenced by: #1.%
  }
\SetUsedByMessage
  {%
    \todo[%
      inline, % Display in-line instead of in the margin.
      size=\scriptsize,
      color=blue!40,
      backgroundcolor=white,
      textcolor=darkgray,
      bordercolor=darkgray,
      prepend]{%
      \textup{\UsedByText{#1}}%
    }%
  }
% \SetUsedByMessageMath
%   {%
%     \marginnote{\UsedByText{#1}}%
%   }
\ExplSyntaxOn
\SetUsedByMessageMath
  {
    \tl_gset:Ne \g_tmpa_tl {\UsedByText{#1}}
  }
\AddToHook{env/equation/before}{\tl_gclear:N \g_tmpa_tl}
\AddToHook{env/equation/after}
  {
    \todo[%
      inline, % Display in-line instead of in the margin.
      size=\scriptsize,
      color=blue!40,
      backgroundcolor=white,
      textcolor=blue!50!cyan,
      bordercolor=blue!50!cyan,
      prepend]{%
      \textup{\tl_use:N \g_tmpa_tl}%
    }%
  }
\ExplSyntaxOff

\begin{document}

\begin{theorem}\label{thm}
  \cref{eq}
\end{theorem}

\begin{lemma}
  \cref{thm}, \cref{eq}
\end{lemma}

\begin{equation}
  \label{eq}
  \int x
  % \meaning\label
\end{equation}

% \meaning\label

\end{document}

---

Un-collapse to see the (newly) modified version of `cleveref-usedon.sty`.

```latex \def\UsedOnPackageVersion{0.4.0x} \def\UsedOnPackageDate{2023-10-17} \NeedsTeXFormat{LaTeX2e}[2021-06-01] \ProvidesExplPackage{cleveref-usedon} {\UsedOnPackageDate} {\UsedOnPackageVersion} {Patches the cleveref package and adds forward-referencing functionality} %% \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.}% } \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.}% } \keys_define:nn { cleveref-usedon } { , Default .tl_set:N = \l__UsedOn_default_tl , Default .initial:n = { } , Default .value_required:n = true , UsedOn .meta:n = { Default = UsedOn } , usedon .meta:n = { Default = UsedOn } , uo .meta:n = { Default = UsedOn } , UsedBy .meta:n = { Default = UsedBy } , usedby .meta:n = { Default = UsedBy } , ub .meta:n = { Default = UsedBy } , UsedByAndOn .meta:n = { Default = UsedByAndOn } , usedbyandon .meta:n = { Default = UsedByAndOn } , ubao .meta:n = { Default = UsedByAndOn } , unknown .code:n = { \PassOptionsToPackage { \CurrentOption } { cleveref } } } \ProcessKeyOptions [ cleveref-usedon ] \RequirePackage{cleveref}[2018/03/27] \newcommand*{\@setcpagerefrange}[3]{% \@@setcpagerefrange{#1}{#2}{cref}{#3}} \newcommand*{\@setCpagerefrange}[3]{% \@@setcpagerefrange{#1}{#2}{Cref}{#3}} \newcommand*{\@setlabelcpagerefrange}[3]{% \@@setcpagerefrange{#1}{#2}{labelcref}{#3}} \prg_generate_conditional_variant:Nnn \str_case:nn { x } { T, TF } \cs_generate_variant:Nn \str_case:nn { x } \seq_new:N \g__UsedOn_k_seq \prop_new:N \g__UsedOn_kv_prop \clist_new:N \g__UsedOn_Options_clist \clist_set:Nn \g__UsedOn_Options_clist { UsedOn, UsedBy, UsedByAndOn } \cs_new:Nn \__UsedOn_UsedOnMessage:n { } \cs_new:Nn \__UsedOn_UsedByMessage:n { } \cs_new:Nn \__UsedOn_UsedByAndOnMessage:nn { } \NewDocumentCommand \UsedOnText { m } { \__UsedOn_UsedOnMessage:n { #1 } } \NewDocumentCommand \UsedByText { m } { \__UsedOn_UsedByMessage:n { #1 } } \NewDocumentCommand \UsedByAndOnText { m } { \__UsedOn_UsedByAndOnMessage:n { #1 } } \NewDocumentCommand \SetUsedOnText { m } { \cs_set:Nn \__UsedOn_UsedOnMessage:n { #1 } } \NewDocumentCommand \SetUsedByText { m } { \cs_set:Nn \__UsedOn_UsedByMessage:n { #1 } } \NewDocumentCommand \SetUsedByAndOnText { m } { \cs_set:Nn \__UsedOn_UsedByAndOnMessage:nn { #1 } } \RequirePackage{iflang} \SetUsedOnText { \IfLanguageName{english} { (Used~on~#1.) } {} \IfLanguageName{french} { (Apparaît~en~#1.) } {} \IfLanguageName{ngerman} { (Wird~auf~#1.) } {} \IfLanguageName{spanish} { (Aparece~en~#1.) } {} } \SetUsedByText { \IfLanguageName{english} { (Used~by~#1.) } {} \IfLanguageName{french} { (Apparaît~dans~#1.) } {} \IfLanguageName{ngerman} { (Wird~in~#1.) } {} \IfLanguageName{spanish} { (Aparece~en~#1.) } {} } \SetUsedByAndOnText { \IfLanguageName{english} { (Used~by~#1~on~#2.) } {} \IfLanguageName{french} { (Apparaît~dans~#1~en~#2.) } {} \IfLanguageName{ngerman} { (Wird~in~#1~auf~#2.) } {} \IfLanguageName{spanish} { (Aparece~en~#1~en~#2.) } {} } \NewDocumentCommand \UsedOnMessage { m } { \emph{ \__UsedOn_UsedOnMessage:n { #1 } } \\[.3\baselineskip] } \NewDocumentCommand \UsedByMessage { m } { \emph{ \__UsedOn_UsedByMessage:n { #1 } } \\[.3\baselineskip] } \NewDocumentCommand \UsedByAndOnMessage { m m } { \emph{ \__UsedOn_UsedByAndOnMessage:nn { #1 } { #2 } } \\[.3\baselineskip] } \NewDocumentCommand \UsedOnMessageMath { m } { % Currently does nothing } \NewDocumentCommand \UsedByMessageMath { m } { % Currently does nothing } \NewDocumentCommand \UsedByAndOnMessageMath { m m } { % Currently does nothing } \NewDocumentCommand \SetUsedOnMessage { m } { \RenewDocumentCommand \UsedOnMessage { m } { #1 } } \NewDocumentCommand \SetUsedByMessage { m } { \RenewDocumentCommand \UsedByMessage { m } { #1 } } \NewDocumentCommand \SetUsedByAndOnMessage { m } { \RenewDocumentCommand \UsedByAndOnMessage { m } { #1 } } \NewDocumentCommand \SetUsedOnMessageMath { m } { \RenewDocumentCommand \UsedOnMessageMath { m } { #1 } } \NewDocumentCommand \SetUsedByMessageMath { m } { \RenewDocumentCommand \UsedByMessageMath { m } { #1 } } \NewDocumentCommand \SetUsedByAndOnMessageMath { m } { \RenewDocumentCommand \UsedByAndOnMessageMath { m } { #1 } } \cs_new:Nn \__UsedOn_Printer_generic:nnn { %% % Check if the reference #1@@1 exists %% % Here the @1 means that has been referenced %% % with option #1 at least once where #1 is %% % 'UsedOn', 'UsedBy' or 'UsedByAndOn' \cs_if_exist:cT {r@#1@#2@1} { %% % In a tmp clist we store all the references of the form %% % `@@` %% % where Number between 1 and \value{LastRun@UsedOn@} %% % if the latter exists, otherwise until 1 %% % Should/will normally need two consecutive runs of pdflatex \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 } #3 } } \NewDocumentCommand \__UsedOn_Printer { m m } { \__UsedOn_Printer_generic:nnn { #1 } { #2 } { %% % 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 \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} } } } } } \NewDocumentCommand \__UsedOn_Printer_Math { m m } { \__UsedOn_Printer_generic:nnn { #1 } { #2 } { %% % 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 \str_case:xn { \str_foldcase:n { #1 } } { {usedon} { \UsedOnMessageMath { \cpageref{\l_tmpa_clist} } } {usedby} { \UsedByMessageMath { \cref{\l_tmpa_clist} } } {usedbyandon} { \UsedByAndOnMessageMath { \cref{\l_tmpa_clist} } { \cpageref{\l_tmpa_clist} } } } } } \NewDocumentCommand \__UsedOn_PrintMessage { m } { \clist_map_inline:Nn \g__UsedOn_Options_clist { \__UsedOn_Printer{##1}{#1} } } \NewDocumentCommand \__UsedOn_PrintMessageMath { m } { \clist_map_inline:Nn \g__UsedOn_Options_clist { \__UsedOn_Printer_Math{##1}{#1} } } \str_new:N \l__UsedOn_Option_str \NewDocumentCommand \__UsedOn_Processor { o m } { \IfValueT{#1}{ \str_case:xnTF { \str_foldcase:n { #1 } } { %% % check if options 'UsedOn', 'UsedBy' or 'UsedByAndOn' %% % (case-insensitive) were used in one of the following forms {usedon} {\str_set:Nn \l__UsedOn_Option_str {UsedOn}} {uo} {\str_set:Nn \l__UsedOn_Option_str {UsedOn}} {usedby} {\str_set:Nn \l__UsedOn_Option_str {UsedBy}} {ub} {\str_set:Nn \l__UsedOn_Option_str {UsedBy}} {usedbyandon} {\str_set:Nn \l__UsedOn_Option_str {UsedByAndOn}} {ubao} {\str_set:Nn \l__UsedOn_Option_str {UsedByAndOn}} } { { %% % Loop through (potential) label list in arg of \cref (or \Cref) \seq_set_from_clist:Nn \l_tmpa_seq {#2} \seq_map_inline:Nn \l_tmpa_seq { %% % 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 \seq_if_in:NxF \g__UsedOn_k_seq { \l__UsedOn_Option_str @##1 } { \newcounter{ ThisRun@ \l__UsedOn_Option_str @##1 } \cs_if_free:cT {c@LastRun@ \l__UsedOn_Option_str @##1} { \newcounter{LastRun@ \l__UsedOn_Option_str @##1} } \seq_gput_right:Nx \g__UsedOn_k_seq { \l__UsedOn_Option_str @##1} } %% % increase the counters and compare with max counter \stepcounter{ThisRun@ \l__UsedOn_Option_str @##1} \setcounter{LastRun@ \l__UsedOn_Option_str @##1} { \fp_eval:n { max( \value{ThisRun@ \l__UsedOn_Option_str @##1} , \value{LastRun@ \l__UsedOn_Option_str @##1} ) } } %% % store the value in global key-value property list \prop_gput:Nxx \g__UsedOn_kv_prop { \l__UsedOn_Option_str @##1} {\arabic{LastRun@ \l__UsedOn_Option_str @##1}} %% % create a label for the UsedOn reference and number this label \__UsedOn_origlabel { \l__UsedOn_Option_str @##1@ \arabic{ThisRun@ \l__UsedOn_Option_str @##1} } } } } { %% % Throw an error, if an unrecognised option was used %% % for the optional argument to this macro. \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 } } } } \bool_new:N \l__UsedOn_already_specified_bool \clist_new:N \l__UsedOn_args_clist \cs_new:Nn \__UsedOn_define_from_orig:NN { \NewDocumentCommand #1 { s o m } { \IfValueTF { ##2 } { \bool_set_false:N \l__UsedOn_already_specified_bool \clist_set:Nn \l__UsedOn_args_clist { ##2 } \clist_put_right:No \l__UsedOn_args_clist { \l__UsedOn_default_tl } \clist_map_inline:Nn \l__UsedOn_args_clist { \str_case:xnT { \str_foldcase:n { ####1 } } { {usedon} {} {uo} {} {usedby} {} {ub} {} {usedbyandon} {} {ubao} {} } { \clist_remove_all:Nn \l__UsedOn_args_clist { ####1 } \bool_if:NF \l__UsedOn_already_specified_bool { \__UsedOn_Processor[####1]{##3} } \bool_set_true:N \l__UsedOn_already_specified_bool } } \clist_if_empty:NTF \l__UsedOn_args_clist { \IfBooleanTF{##1}{ #2*{##3} }{ #2{##3} } } { \IfBooleanTF{##1}{ #2*[\l__UsedOn_args_clist]{##3} }{ #2[\l__UsedOn_args_clist]{##3} } } } { \tl_if_blank:VF \l__UsedOn_default_tl { \clist_clear:N \l__UsedOn_args_clist \clist_put_right:No \l__UsedOn_args_clist { \l__UsedOn_default_tl } \clist_map_inline:Nn \l__UsedOn_args_clist { \__UsedOn_Processor[####1]{##3} } } \IfBooleanTF{##1}{ #2*{##3} }{ #2{##3} } } } } \__UsedOn_define_from_orig:NN \__UsedOn_cref \__UsedOn_origcref \__UsedOn_define_from_orig:NN \__UsedOn_Cref \__UsedOn_origCref \__UsedOn_define_from_orig:NN \__UsedOn_labelcref \__UsedOn_origlabelcref \NewDocumentCommand \__UsedOn_ReadFromAux { } { \prop_map_inline:Nn \g__UsedOn_kv_prop { \newcounter{LastRun@##1} \setcounter{LastRun@##1}{##2} } } \NewDocumentCommand \__UsedOn_WriteToAux { } { %% % 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. \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}} } %% % Turn on |expl3| functionality in .aux file. \iow_now:cx { @auxout } { \token_to_str:N \ExplSyntaxOn } %% % Loop through the key-val |proplist| and write contents to .aux file. \prop_map_inline:Nn \g__UsedOn_kv_prop { \tl_set:Nn \l_tmpa_tl { ##1 } \tl_replace_all:Nnn \l_tmpa_tl { ~ } { \c_tilde_str } \iow_now:cx { @auxout } { \prop_gput_from_keyval:Nn \token_to_str:N \g__UsedOn_kv_prop { {\l_tmpa_tl} = ##2 } } } %% % Turn off |expl3| functionality in .aux file. \iow_now:cx { @auxout } { \token_to_str:N \ExplSyntaxOff } }% \hook_gput_code:nnn { begindocument/end } { cleveref-usedon } { \__UsedOn_ReadFromAux \cs_if_exist:NF \label@in@display { \NewCommandCopy \label@in@display \label } \NewCommandCopy \__UsedOn_origlabel@in@display \label@in@display \NewCommandCopy \__UsedOn_origlabel \label \NewCommandCopy \__UsedOn_origcref \cref \NewCommandCopy \__UsedOn_origCref \Cref \NewCommandCopy \__UsedOn_origlabelcref \labelcref \RenewDocumentCommand \label { o m } { \if_mode_math: % this is for ntheorem \IfValueTF { #1 } { \__UsedOn_origlabel@in@display[#1]{#2} } { \__UsedOn_origlabel@in@display{#2} } \__UsedOn_PrintMessageMath{#2} \else: \IfValueTF { #1 } { \__UsedOn_origlabel[#1]{#2} } { \__UsedOn_origlabel{#2} } \__UsedOn_PrintMessage{#2} \fi: } \RenewDocumentCommand \label@in@display { o m } { \IfValueTF { #1 } { \__UsedOn_origlabel@in@display[#1]{#2} } { \__UsedOn_origlabel@in@display{#2} } \__UsedOn_PrintMessageMath{#2} } \RenewCommandCopy \cref \__UsedOn_cref \RenewCommandCopy \Cref \__UsedOn_Cref \RenewCommandCopy \labelcref \__UsedOn_labelcref } \hook_gput_code:nnn { enddocument } { cleveref-usedon } { \__UsedOn_WriteToAux } \endinput %% %% End of file `cleveref-usedon.sty'. ```

[Jinwen-XU]

The code in https://github.com/SvenPistre/cleveref-usedon/issues/10#issuecomment-1770748342 gives a version that works for many types of displayed equations, with a new syntax for text and style configuration supported. With that version, it is possible to either print the Message in the margin as you originally suggested (via \SetUsedByMessageInsideMath), or print the Message as usual (via \SetUsedByMessageOutsideMath).