path: root/macros/latex/contrib/crossreftools/crossreftools_doc.tex

%% LaTeX package crossreftools - version 1.0 (2020/07/19 -- 11:55:58)
%% Documentation file for crossreftools.sty
%%
%%
%% -------------------------------------------------------------------------------------------
%% Copyright (c) 2017 -- 2020 by Dr. Christian Hupfer <dr dot christian dot hupfer at gmail dot com>
%% -------------------------------------------------------------------------------------------
%%
%% This work 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 has the LPPL maintenance status `author-maintained`
%%
%%

\documentclass[12pt,a4paper,oneside]{article}

\usepackage[T1]{fontenc}
\usepackage{graphicx}%


\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{minitoc}
\usepackage{tocbibind}





\usepackage[lmargin=2cm,rmargin=2cm,headheight=15pt]{geometry}
\usepackage{savesym}
\usepackage{bbding}
\savesymbol{Cross}

\usepackage{graphicx}
\usepackage{blindtext}
\usepackage[x11names]{xcolor}
\usepackage{imakeidx}
\usepackage{fontawesome}
\usepackage[tikz]{bclogo}
\usepackage{marginnote}
\usepackage{fancyhdr}
\usepackage{datetime}
\usepackage{array}
\usepackage{xkeyval}
\usepackage{xparse}
\usepackage{totcount}
\usepackage{enumitem}
\usepackage{caption}
\usepackage{microtype}
\usepackage[T1]{fontenc}
\usepackage[scaled=0.92]{helvet}

\usepackage[most,documentation]{tcolorbox}


\newlist{codeoptionsenum}{enumerate}{1}
\setlist[codeoptionsenum,1]{label={\textcolor{blue}{\#\arabic*}}}

\renewcommand{\rmdefault}{\sfdefault}

\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}

\makeatletter
\define@key{chdoc}{packageauthor}{%
  \def\KVchdocpackageauthor{#1}%
}

\define@key{chdoc}{packageauthormail}{%
  \def\KVchdocpackageauthormail{#1}%
}

\define@key{chdoc}{filepurpose}{%
  \def\KVchdocfilepurpose{#1}%
}


\newcommand{\chdocextractversion}[1]{%
  \@nameuse{#1}%
}


\@namedef{crossreftoolsversion0.1}{v0.1 2017-10-08}

\@namedef{crossreftoolsversion0.2}{v0.2 2017-10-25}

\@namedef{crossreftoolsversion0.3}{v0.3 2017-10-29}

\@namedef{crossreftoolsversion0.4}{v0.4 2017-12-26}

\@namedef{crossreftoolsversion0.5}{v0.5 2018-02-23}

\@namedef{crossreftoolsversion0.6}{v0.6 2018-03-18}

\@namedef{crossreftoolsversion0.7}{v0.7 2018-12-28}

\@namedef{crossreftoolsversion0.8}{v0.8 2018-12-29}

\@namedef{crossreftoolsversion0.9}{v0.9 2019-01-03}

\@namedef{crossreftoolsversion1.0}{v1.0 2020-07-19}

\newcommand{\authorname}{Autor}


\makeatother






\fancypagestyle{plain}{%
\fancyfoot[L]{\begin{tabular}[t]{l}\PackageDocName\ \packageversion \tabularnewline \textcopyright\ Dr. Christian Hupfer\end{tabular}}%
\fancyfoot[C]{\thepage}%
\fancyfoot[R]{\today}%
\renewcommand{\headrule}{{\color{blue}%
\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}}
\renewcommand{\footrule}{{\color{blue}\vskip-\footruleskip\vskip-\footrulewidth
\hrule width\headwidth height\footrulewidth\vskip\footruleskip}}
\renewcommand{\footrulewidth}{2pt}
\renewcommand{\headrulewidth}{2pt}
}



\newtcolorbox{CHPackageTitleBox}[1][]{%
  enhanced jigsaw,
  drop lifted shadow,
  colback=yellow!30!white,
  width=0.8\textwidth,
  #1
}

\presetkeys{chdoc}{packageauthor={Christian Hupfer}}{}%
\NewDocumentCommand{\CHPackageTitlePage}{O{}mO{}}{%
  \setkeys{chdoc}{packageauthor={Christian Hupfer},filepurpose={Documentation},#1}%
  \begin{center}
    \begin{CHPackageTitleBox}[#3]
      \large \bfseries%
      \begin{center}%
        \begin{tabular}{C{0.9\textwidth}}%
          \scshape \PackageDocName \tabularnewline
          \tabularnewline
          #2 \tabularnewline
          \tabularnewline
          \KVchdocfilepurpose \tabularnewline
          \tabularnewline
          Version \packageversion \tabularnewline
          \tabularnewline
          \today \tabularnewline
          \tabularnewline
          \addtocounter{footnote}{2}
          \authorname: \KVchdocpackageauthor\(^\mathrm{\fnsymbol{footnote}}\)
          \tabularnewline
        \end{tabular}
      \end{center}
    \end{CHPackageTitleBox}
    \renewcommand{\thefootnote}{\fnsymbol{footnote}}%
    \footnotetext{\mymailtoaddress}%
  \end{center}
}

\newtcolorbox{docCommandArgs}[1]{colbacktitle={blue},coltitle={white},title={Description of arguments of command \cs{#1}}}


\newcommand{\tcolorboxdoclink}{http://mirrors.ctan.org/macros/latex/contrib/tcolorbox/tcolorbox.pdf}

% 'Stolen' from tcolorbox documentation ;-)

\newtcolorbox{marker}[1][]{enhanced,
  before skip=2mm,after skip=3mm,
  boxrule=0.4pt,left=5mm,right=2mm,top=1mm,bottom=1mm,
  colback=yellow!50,
  colframe=yellow!20!black,
  sharp corners,rounded corners=southeast,arc is angular,arc=3mm,
  underlay={%
    \path[fill=tcbcolback!80!black] ([yshift=3mm]interior.south east)--++(-0.4,-0.1)--++(0.1,-0.2);
    \path[draw=tcbcolframe,shorten <=-0.05mm,shorten >=-0.05mm] ([yshift=3mm]interior.south east)--++(-0.4,-0.1)--++(0.1,-0.2);
    \path[fill=yellow!50!black,draw=none] (interior.south west) rectangle node[white]{\Huge\bfseries !} ([xshift=4mm]interior.north west);
    },
    drop fuzzy shadow,#1}


%%%% Documentation macros


\NewDocumentCommand{\packagename}{sm}{%
  \textcolor{blue}{\textbf{\faEnvelopeO~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}
  }%
}

\NewDocumentCommand{\classname}{sm}{%
  \textcolor{brown}{\textbf{\faBriefcase~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}%
  }%
}


\NewDocumentCommand{\CHDocPackage}{sm}{%
  \textcolor{blue}{\textbf{\faEnvelopeO~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}
  }%
}




\NewDocumentCommand{\CHDocClass}{sm}{%
  \textcolor{brown}{\textbf{\faBriefcase~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}%
  }%
}

\NewDocumentCommand{\CHDocKey}{sm}{%
  \textcolor{red}{\textbf{\faKey~#2}}%
  \IfBooleanF{#1}{%
      \index{Option!#2}%
  }%
}

\newcommand{\handrightnote}{\tcbdocmarginnote{\ding{43}}}


\NewDocumentCommand{\CHDocCounter}{sm}{%
  \textcolor{Green4}{\textbf{\faCalculator~#2}}%
  \IfBooleanF{#1}{%
    \index{Counter!#2}%
  }%	
}


\NewDocumentCommand{\CHDocTag}{sm}{%
  \textcolor{violet}{\faTag~#2}%
  \IfBooleanF{#1}{%
    \index{Feature!#2}%
  }%	
}


\NewDocumentCommand{\CHDocFileExt}{sm}{%
    \faFile~#2%
}

\NewDocumentCommand{\CHDocFiles}{sm}{%
    \faFilesO~#2%
}


\NewDocumentCommand{\CHDocConventions}{}{%
  \section*{\centering Typographical conventions}
  Throughout this documentation following symbols and conventions are used:
  \begin{itemize}
  \item \CHDocClass*{foo} means a the class \texttt{foo}
  \item \CHDocPackage*{foo} names a package \texttt{foo}
  \item \CHDocCounter*{foo} indicates a counter named \texttt{foo}
  \item \CHDocFileExt*{foo} will indicate either a file named \texttt{foo} or a file extension \texttt{foo}
  \item \CHDocFiles*{foo} will indicate some files 
  \item \CHDocTag*{foo} names a special feature or tag \texttt{foo}
  \item \CHDocKey*{foo} deals with a command or package option named \texttt{foo}
  \end{itemize}
}



\renewcommand{\tcbdocnew}[1]{#1}%
\renewcommand{\tcbdocupdated}[1]{#1}%

\newcommand{\CHDocNew}[1]{%
  \tcbdocmarginnote[doclang/new={N},
  colframe=blue,
  halign=left,
  colback={blue!20!white},
  fontupper={\tiny}
  ]{%
    \chdocextractversion{crossreftoolsversion#1}%
  }%
}



\newcommand{\CHDocUpdate}[1]{\tcbdocmarginnote[doclang/updated={},colback={yellow},colframe={yellow!50!red},  fontupper={\tiny}
]{%
  \tcbdocupdated{\chdocextractversion{crossreftoolsversion#1}}%
}%
}



\newcommand{\CHDocFullVersion}[1]{Version \chdocextractversion{crossreftoolsversion#1}}


\newcommand{\CHDocExpCommand}[1][Expandable]{%
  \tcbdocmarginnote[doclang/new={N},
  colframe=green!50!blue,
  halign=left,
  colback={green!90!blue},
  fontupper={\tiny}
  ]{%
    #1%
  }%
}


\newcommand{\CHDocExperimentalFeature}[1][Experimental]{%
  \tcbdocmarginnote[doclang/new={N},
  colframe=yellow!50!blue,
  halign=left,
  colback={blue!10!yellow},
  fontupper={\tiny}
  ]{%
    #1%
  }%
}



\usepackage{bookmark}


\usepackage{cleveref}




\def\packageversion{1.0}

\def\hyperrefversionwithfifthargument{v6.85a}

\usepackage{url}

\setcounter{tocdepth}{3}
\newcommand{\PackageDocName}{crossreftools}%


\newcommand{\mymailtoaddress}{%
  dr.christian.hupfer@gmail.com%
}

\doparttoc

\makeindex[intoc]


\renewcommand{\rmdefault}{\sfdefault}



\hypersetup{breaklinks=true,
  pdftitle={\jobname.pdf -- version \packageversion},
  pdfauthor={Dr. Christian Hupfer},
  pdfsubject={Documentation of \PackageDocName\ package},
  pdfkeywords={LaTeX, cross-referencing},
  bookmarksopen=true,
  bookmarksopenlevel=2,
  bookmarksnumbered=true,
  pdfcreator={LaTeX}
}

% Load here!

\AtEndPreamble{
  \usepackage{crossreftools}
}



\begin{document}

\yyyymmdddate


\setlength{\parindent}{0em}

\pagestyle{empty}%



\CHPackageTitlePage[packageauthor={Christian Hupfer}]{Expandable extraction of cleveref or cross reference data and label utilities}


\clearpage
\tableofcontents
\clearpage

\CHDocConventions
\clearpage

\crtlistoflabels


\pagestyle{plain}


\setcounter{footnote}{0}

\part{Introduction}

\parttoc

\section*{Preface}

This package provides expandable extraction of information stored in labels generated with \CHDocPackage{cleveref} and regular labels written by the usual \cs{label} macro, regardless whether \CHDocPackage{hyperref} is loaded or not. For those regular cross-reference information \CHDocPackage{\PackageDocName} works in a \CHDocPackage{refcount} - like manner. 

Whereas \CHDocPackage{cleveref} provides \cs{labelcref} and other commands or \cs{ref} from standard \LaTeX2e kernel none of those are expandable and can not be used in an \cs{edef} - approach. 

\begin{marker}
Most times class and package authors will benefit of this package, but there might be usual documents that need the features of \CHDocPackage{\PackageDocName}
\end{marker}

All macros from this package use the prefix \cs{crt\dots}, eg \refCom{crtrefname}. 

\section{Requirements, loading and incompatibilities}%



\subsection{Required packages and \TeX\ engine}

The package does not require features from Xe\LaTeX\ or Lua\LaTeX\ but can be run with those features as well as with \LaTeX\ or pdf\LaTeX. The compilation documentation requires however pdf\LaTeX\ as of version \packageversion. 

No packages are loaded by \CHDocPackage{crossreftools}, this package does neither load \CHDocPackage{hyperref} nor \CHDocPackage{cleveref} itself. 


\subsection{Loading of the package} \label{subsection::loadingofpackage}

Loading is done with

\begin{tcolorbox}
\verb!\usepackage[options]{crossreftools}!
\end{tcolorbox}

As of version \packageversion\ \CHDocPackage{\PackageDocName} does have following option(s):

\begin{itemize}
  \item \texttt{draft}
    
    By default, unless specified as package or class option, \CHDocPackage{\PackageDocName} works in draft mode, i.e. \CHDocTag{List of Labels} is enabled, see \crtcrefcounter{section::listoflabels} \nameref{section::listoflabels} for more on this. 
    
  \item \texttt{final}

    This disables the feature \CHDocTag{List of Labels}, see \crtcrefcounter{section::listoflabels} \nameref{section::listoflabels} for more information about this feature -- it is considered to be unnecessary having a List of Labels in a final version of document. 

By default, the package works in \texttt{draft} - mode, unless the class option \texttt{final} is specified already. In this case, the package option \texttt{final} can be omitted. 
\item \texttt{cleverefcompat}

Use this option if the \CHDocPackage{cleveref} version is older than 0.21. 

\begin{marker}
With the release of \CHDocPackage{cleveref} version 0.21 (dating to 2018/02/08) the format of stored information by \cs{label} changed and causes wrong output of \refCom{crtcrefpage}. Since version \makeatletter\@nameuse{crossreftoolsversion0.5}\makeatother\ this change is caught with \refCom{crtcrefpage}. 
\end{marker}
\end{itemize}




There is no loading order required. The macros related to \CHDocPackage{cleveref} expand to \makeatletter\fbox{\crt@refundefined}\makeatother\ if \CHDocPackage{cleveref} is not loaded. 

\begin{marker}
  In order to ensure that the changes to the cross referencing system introduced by \CHDocPackage{hyperref} and \CHDocPackage{cleveref} it is recommened to load \CHDocPackage{\PackageDocName} after both packages. 
\end{marker}

\subsection{Incompatibilities}\label{subsection:incompatibilities}

\begin{itemize}
  \item Plain \TeX:

    
As of \packageversion\ this package cannot be used with plain \TeX, since there is no real built-in support for cross-referencing in plain \TeX. 
\item Issue with \cs{tcb@cs} from the \CHDocPackage{tcolorbox} and its \fbox{documentation} library regarding the \cs{crtlistoflabels} usage. 

  As of \packageversion\ this package cannot cope with labels produced from \CHDocPackage{tcolorbox} for documented code -- this inserts an unexpandable call of \cs{tcb@cs} in the label content which leaves unpleasant content in the List Of Labels (see \nameref{section::listoflabels}). As long as no other solution is available, \cs{tcb@cs} is redefined to gobble its argument only and doing nothing inside the \refCom{crtlistoflabels} macro. 

\begin{marker}
  This is the cause for the special \cs{refCom} macro provided by the documentation library from \CHDocPackage{tcolorbox}.
\end{marker}
  
\item Similarly any unexpandable content written to the \CHDocFileExt{aux} - file by redefinitions of \cs{label} or \cs{@currentlabel} etc. will cause problems. 
\end{itemize}

\clearpage

\part{Macro descriptions}

\parttoc

\section{Indicating undefined references}

\CHDocPackage{\PackageDocName} uses the content of the internal macro \cs{crt@refundefined} which defaults to \makeatletter\crt@refundefined\makeatother. 
Use \refCom{crtrefundefinedtext} to change the output of \cs{crt@refundefined}.

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtrefundefinedtext}{\marg{undefined reference indication text}}


This command sets the output of \cs{crt@refundefined} in the same manner like the standard macro \cs{title} would do for \cs{@title}. 

\begin{marker}
  \refCom{crtrefundefinedtext} is a preamble-only macro. 
\end{marker}
\end{docCommand}


Similar to \refCom{crtrefundefinedtext} is \refCom{crtcrefundefinedcountervalue}, providing an integer value in calculation contexts with \cs{ifnum} or \cs{setcounter}. 

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtcrefundefinedcountervalue}{\marg{integer value}}


This command sets the output of \cs{crt@crefundefinedcountervalue} in the same manner like the standard macro \cs{title} would do for \cs{@title}. 

\begin{marker}
  \refCom{crtcrefundefinedcountervalue} is a preamble-only macro. 
\end{marker}
\end{docCommand}


\section{Extracting information from regular labels}\label{section:extractingregularlabels}

Depending on loading of \CHDocPackage{hyperref} there is some more information (properties) stored with a \cs{label} command. Common properties are \texttt{reference} and \texttt{page}, additions of \CHDocPackage{hyperref} are \texttt{name}, \texttt{anchor} and the (yet) unused 5th argument of \cs{newlabel}, the property is called \texttt{unused} as of version \packageversion.

All properties are extracted with \refCom{crtextractref}. 



\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.3}}]{crtextractref}{\marg{property}\marg{label name}}

This command will extract one of the properties \texttt{reference}, \texttt{page}, \texttt{anchor}, \texttt{name} and \texttt{unused} from the label given as the 2nd mandatory argument. 
\end{docCommand}

For convenience, there are shortcuts to extract a specific property:

\begin{docCommand}[code={\CHDocExpCommand{}},doc new and updated={\chdocextractversion{crossreftoolsversion0.3}}{\chdocextractversion{crossreftoolsversion0.5}},after=\par]{crtcrefpage}{\marg{label name}}%

  This extracts the page number that would be printed by \cs{cpageref}. 
\end{docCommand}


\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.3}}]{crtrefnumber}{\marg{label name}}

This extracts the reference value (or something that is stored by \cs{@currentlabel} belonging to a certain label name.
\end{docCommand}

With \CHDocPackage{hyperref} being loaded, following commands return non-empty label information, without \CHDocPackage{hyperref} they are available, but expand to nothing.

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.3}}]{crtrefname}{\marg{label name}}

This extracts the name of the sectioning unit or counter as being specified with \cs{nameref}. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.3}}]{crtrefanchor}{\marg{label name}}

This extracts the hyper target anchor of the reference in order to be used with \cs{hyperlink}.
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.3}}]{crtrefunused}{\marg{label name}}

This extracts the yet unused 5th argument of labels generated after \CHDocPackage{hyperref} is loaded. As of version \hyperrefversionwithfifthargument\ of \CHDocPackage{hyperref}, this argument has no meaning yet. If this is going to be change in future, \refCom{crtrefunused} will probably be removed and replaced by another macro that reflects the meaning of this 5th argument. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtrefcounter}{\marg{label name}}

This macro tries to extract the counter name related to the label assuming that the standard anchor type is used: \texttt{X.Y} where \texttt{X} stands for the counter name and \texttt{Y} is some alphanumerical value constructed from \cs{theHX}, e.g. \cs{theHchapter}. If this pattern fails, \refCom{crtrefcounter} will not compile. 

\end{docCommand}


\section{Extracting information from cleveref}

The \CHDocPackage{cleveref} package redefines the \cs{label} macro and stores another label with the same basic name and a suffix \string @cref, so 

\tcbinputlisting{breakable,listing only,listing file=labelstuff.tex}

%\begin{tcblisting}{listing only}
%\section{Stuff}
%\end{tcblisting}

would generate both the labels \verb!foo! and \verb!foo@cref!. The \CHDocPackage{cleveref} - version of a label saves basically five properties to the \CHDocFileExt{.aux} - file. 


\begin{itemize}
  \item \texttt{counter}

    This property holds the name of the counter that was used in \cs{refstepcounter}.


  \item \texttt{number}

    This property holds the value of label, this is usually the value of a counter
    \begin{marker}
      Please note that this property does not mean the reference value that is displayed with \cs{cref} or \cs{Cref}. 
    \end{marker}
  \item \texttt{result}
    
  \item \texttt{reference}
    This property holds the reference that is to be typeset, i.e. the content displayed with \cs{cref} or \cs{Cref}, however, without hyperlinks. 

  \item \texttt{page}
    This property stores the page number of the \cs{label} usage.
    
\end{itemize}
\CHDocPackage{\PackageDocName} extracts those properties with \refCom{crtextractcref}. 

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtextractcref}{\marg{property}\marg{label name}}

This command will extract one of the properties \texttt{counter}, \texttt{number}, \texttt{result}, \texttt{reference} and \texttt{page} from the label given as the 2nd mandatory argument. 
\end{docCommand}

For convenience, there are shortcuts to extract a specific property:

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefcounter}{\marg{label name}}

This extracts the counter belonging to a certain label name.
\end{docCommand}


\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefnumber}{\marg{label name}}

This extracts the counter value (or something that is stored by \cs{cref@currentlabel} belonging to a certain label name.
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.8}}]{crtcrefcountervalue}{\marg{label name}}

This extracts the counter value (or something that is stored by \cs{cref@currentlabel} belonging to a certain label name and can be used in any context that requrires integer values.

If the label does not exist, the content of \cs{crt@crefundefinedcountervalue} is returned, which is by default a number, see \refCom{crtcrefundefinedcountervalue} in order how to set the return value. 
\end{docCommand}


\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefresult}{\marg{label name}}

This extracts the result of the splitting of a counter belonging to a certain label name.
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefreference}{\marg{label name}}

This extracts the reference that would be printed by \cs{cref} or \cs{Cref}, without hyperlinks.
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefname}{\marg{counter name}}

This extracts the lower case cross reference name of a given counter. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtCrefname}{\marg{counter name}}

This extracts the upper case cross reference name of a given counter. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefpluralname}{\marg{counter name}}

This extracts the lower case cross reference plural name of a given counter. 
\end{docCommand}


\begin{docCommand}[code={\CHDocExpCommand{}},
doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtCrefpluralname}{\marg{counter name}}

This extracts the upper case cross reference plural name of a given counter. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new and updated={\chdocextractversion{crossreftoolsversion0.1}}{\chdocextractversion{crossreftoolsversion0.2}}]
{crtcrefnamebylabel}{\marg{label name}}

This extracts the lower case cross reference name of a given label. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new and updated={\chdocextractversion{crossreftoolsversion0.1}}{\chdocextractversion{crossreftoolsversion0.2}}]
{crtCrefnamebylabel}{\marg{label name}}

This extracts the upper case cross reference name of a given label. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new=\chdocextractversion{crossreftoolsversion0.3}]
{crtcref}{\marg{label name}}

This displays the reference in the same way as \cs{cref} from \CHDocPackage{cleveref} would do in a setup without using \cs{crefformat} etc. The hyperlink is not displayed, however. This command is expandable. 

For the upper case version see \refCom{crtCref}. 
\end{docCommand}

\begin{docCommand}[code={\CHDocExpCommand{}},
doc new=\chdocextractversion{crossreftoolsversion0.3}]
{crtCref}{\marg{label name}}

This displays the reference in the same way as \cs{Cref} from \CHDocPackage{cleveref} would do in a setup without using \cs{Crefformat} etc. The hyperlink is not displayed, however. This command is expandable. 

For the lower case version see \refCom{crtcref}. 
\end{docCommand}

\subsection{Nonexpandable Commands}


\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.3}]
{crthyperlink}{\marg{anchor}\marg{link text}}

This is a wrapper to the \cs{hyperlink} macro from \CHDocPackage{hyperref} to the given \marg{anchor}, displaying the \marg{link text}. If \CHDocPackage{hyperref} is not loaded, only the link text is displayed. 
\end{docCommand}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.3}]
{crthypercref}{\marg{label name}}

This generates a linked reference to a given label like \cs{cref} would do. If \CHDocPackage{hyperref} is not loaded, no link but only the reference text is displayed. 

For the upper case version see \refCom{crthyperCref}. 
\end{docCommand}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.3}]
{crthyperCref}{\marg{label name}}

This generates a linked reference to a given label like \cs{Cref} would do. If \CHDocPackage{hyperref} is not loaded, no link but only the reference text is displayed. 

For the lower case version see \refCom{crthypercref}. 
\end{docCommand}

\section{Lower and upper case references}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtlnameref}{\marg{label name}}

This generates a linked reference to the name like \cs{nameref} would do, but the first character is used in lower case mode. % given label like \cs{Cref} would do. 
If \CHDocPackage{hyperref} is not loaded, no link but only the reference text is displayed. 
For the upper case version see \refCom{crtunameref}. 
\end{docCommand}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtlnameref*}{\marg{label name}}

This generates a reference like \cs{nameref*} would do, but the first character is used in lower case mode -- no links are generated. 
For the upper case version see \refCom{crtlnameref*}. 
\end{docCommand}


\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtunameref}{\marg{label name}}

This generates a linked reference to the name like \cs{nameref} would do, but the first character is used in upper case mode. % given label like \cs{Cref} would do. 
If \CHDocPackage{hyperref} is not loaded, no link but only the reference text is displayed. 
For the lower case version see \refCom{crtlnameref}. 
\end{docCommand}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtunameref*}{\marg{label name}}

This generates a reference like \cs{nameref*} would do, but the first character is used in upper case mode -- no links are generated. 
For the lower case version see \refCom{crtlnameref*}. 
\end{docCommand}


\section{Convenience macros}

In case \CHDocPackage{hyperref} shouldn't be loaded, \CHDocPackage{crossreftools} provides some convenience wrapper macros

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtnameref}{\marg{label name}}

This generates a reference like \cs{nameref*} would do. 
If \CHDocPackage{hyperref} is not loaded but \CHDocPackage{nameref} is used, no link is generated, so \refCom{crtnameref} acts like \refCom{crtnameref*}
For the unlinked version see \refCom{crtnameref*}. 
\end{docCommand}

\begin{docCommand}[doc new=\chdocextractversion{crossreftoolsversion0.6}]
{crtnameref*}{\marg{label name}}

This generates a reference like \cs{nameref*} would do and does not generate a link. If neither \CHDocPackage{nameref} nor \CHDocPackage{hyperref} is used no output is generated from this macro. 
For the linked version see \refCom{crtnameref}. 
\end{docCommand}


\section{Placing more generic labels}\label{section::placing-generic-labels}

Sometimes it is necessary to refer to content that is not connected to a counter and \cs{refstepcounter}. In this case the macros \refCom{crtprovidecurrentlabel}, \refCom{crtprovidecurrentlabelname}, 

\refCom{crtprovidecurrentlabelinfo} and \refCom{crtcrossreflabel} may be useful.

\begin{marker}
  None of the macros placing 'arbitrary' labels described in this section is expandable! 
\end{marker}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtprovidecurrentlabel}{\marg{usual label content}}
This sets \cs{@currentlabel} which is later on stored to be the label content with \cs{label} and being displayed with the various variants of \cs{ref} or \cs{cref} etc. from \CHDocPackage{cleveref}. 
\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtprovidecurrentlabelname}{\marg{nameref label content}}
This sets \cs{@currentlabelname} which is later on stored to be the label content with \cs{label} and being displayed with the various variants of \cs{nameref} from \CHDocPackage{hyperref}. 
\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtprovidecurrentlabelinfo}{\marg{usual label content}\marg{nameref label content}}
This is a convenience macro in order to provide both \cs{@currentlabel} and \cs{@currentlabelname} at once. If \CHDocPackage{hyperref} is loaded, a \cs{phantomsection} call is used before calling

\refCom{crtprovidecurrentlabel} and \refCom{crtprovidecurrentlabelname}.
\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtcrossreflabel}{\oarg{nameref label content}\marg{usual label content}\oarg{label name}}

This macro is an even more convenient wrapper for \refCom{crtprovidecurrentlabelinfo} by using the 2nd (mandatory) argument both for the usual label and the nameref label content if the 1st optional argument is not specified. This resembles the \cs{caption[]\textbraceleft\textbraceright} or e.g. \cs{section[]\textbraceleft\textbraceright} mechanism where the first optional argument is used for the ToC - related entries. 

The 2nd optional argument is placing the \cs{label} with the relevant label name. 

\begin{marker}
  Please note that depending on the presence of the 1st optional argument either the 2nd or der 1st argument is displayed in the input stream, i.e. in the document text. If this is not requested, use the starred form \refCom{crtcrossreflabel*}.
\end{marker}


\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtcrossreflabel*}{\oarg{nameref label content}\marg{usual label content}\oarg{label name}}

This behaves like \refCom{crtcrossreflabel} but suppresses the output of the 2nd or 1st argument explicitly. Use this to place hidden labels and anchors. 
\end{docCommand}


\clearpage
\section{Checking for label existence}\label{sec:checkinglabelexistence}

Sometimes it is necessary to check whether some label exists in order to refer to it. The macros 

\begin{itemize}
  \item \refCom{crtifdefinedlabel}
  \item \refCom{crtcrefifdefinedlabel}
\end{itemize}

check for the label existence and execute the relevant true or false conditions for labels defined the usual \cs{label} macro and for their \CHDocPackage{cleveref} version. 

Those macros have related commands that revert the test, i.e. they check for the non-existence of a label:

\begin{itemize}
  \item \refCom{crtifundefinedlabel}
  \item \refCom{crtcrefifundefinedlabel}
\end{itemize}


\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.5}}]{crtifdefinedlabel}{\marg{label name}\marg{true branch}\marg{false branch}}
This checks whether the label 'label name' is defined and executes the true branch, otherwise the false branch. 
\end{docCommand}


\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.5}}]{crtifundefinedlabel}{\marg{label name}\marg{true branch}\marg{false branch}}
This checks whether the label 'label name' is undefined and executes the true branch, otherwise the false branch. 
\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.5}}]{crtcrefifdefinedlabel}{\marg{label name}\marg{true branch}\marg{false branch}}
This checks whether the label 'label name' is defined by \CHDocPackage{cleveref} and executes the true branch, otherwise the false branch. 
\end{docCommand}


\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.5}}]{crtcrefifundefinedlabel}{\marg{label name}\marg{true branch}\marg{false branch}}
This checks whether the label 'label name' is undefined by \CHDocPackage{cleveref} and executes the true branch, otherwise the false branch. 
\end{docCommand}



\section{Displaying label information}\label{section::listoflabels}

For some reason it might be useful to have a list of all defined labels available. Currently, the support from \CHDocPackage{crossreftools} for this limited, however. 

\begin{marker}
  \CHDocPackage{crossreftools} redefines \cs{label} at the beginning of the document body. It takes care about a potential optional argument of \cs{label} as is introduced by \CHDocPackage{cleveref}. 
\end{marker}


\subsection{Useful macros for the list of labels}




\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtlistoflabels}{}
This displays a list of all cross-reference labels in the order of their definition, the heading has the title \texttt{\listoflabelsname}, in order to change the title redefine \refCom{listoflabelsname}. 

An ordinary entry to the list - of - labels file (default extension \CHDocFileExt{lla}) is written with \cs{addcontentsline} 

\tcbinputlisting{breakable,listing only,listing file=addcontentslineforlistoflabels.tex}

where \refCom{crt@listoflabelsfileextension} and \refCom{crt@listoflabelsstructurelevel} are internal versions of \refCom{crtlistoflabelsfileextension} and

\refCom{crtlistoflabelsstructurelevel}.

This command does add an entry into the table of contents (\CHDocFileExt{toc} - file) either on chapter or on section level, depending whether the class is \CHDocClass{book} or not. 

If no ToC - entry should be made, use \refCom{crtlistoflabels*}.

\begin{marker}
  If the package (or class) option \texttt{final} is enabled, the \CHDocTag{List of Labels} feature is disabled and \refCom{crtlistoflabels} expands to nothing. 
\end{marker}


\end{docCommand}


\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtlistoflabels*}{}
This behaves like \refCom{crtlistoflabels} but does not generate an entry in the table of contents. 

\end{docCommand}



\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtlistoflabelsfileextension}{\marg{extension}}

This changes the extention of the list of labels file. The value is stored internally in

 \refCom{crt@listoflabelsfileextension} which defaults to \texttt{lla}

\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crt@listoflabelsfileextension}{}

This holds the extension (without a dot in the name) of the list of labels file. Do not change this macro directly, but use \refCom{crtlistoflabelsfileextension} instead. 

\end{docCommand}


\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{listoflabelsname}{}
This is the title of the list of labels heading, it defaults to \texttt{\listoflabelsname}. 

It can be changed with \cs{renewcommand}. 

\end{docCommand}




\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtlistoflabelsstructurelevel}{\marg{counter name}}

This changes the level of the label entries in the list of labels. The value is stored internally in \cs{crt@listoflabelsstructurelevel} which defaults to \texttt{section}

\begin{marker}
This is a preamble - only macro. 
\end{marker}
\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crt@listoflabelsstructurelevel}{}

This holds the structure level of the list of labels entries. Do not change this macro directly, but use \refCom{crtlistoflabelsstructurelevel} instead. 

\end{docCommand}


\subsection{Useful macros for the label command}

\CHDocPackage{crossreftools} provides two hook macros to be usable inside of the \cs{label} command

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtprelabelhook}{\marg{argument}}
This hook is executed before the internally stored \cs{label} is called, the argument can be 'anything'. 

By default, this macro expands to nothing, but can be redefined with \cs{renewcommand}. 

\end{docCommand}

\begin{docCommand}[doc new={\chdocextractversion{crossreftoolsversion0.4}}]{crtpostlabelhook}{\marg{argument}}
This hook is executed after the internally stored \cs{label} is called, the argument can be 'anything'. 

By default, this macro expands to nothing, but can be redefined with \cs{renewcommand}. 

\end{docCommand}


\clearpage
\part{Examples}

\parttoc

\section{Driver example}

\tcbinputlisting{breakable,listing only,listing file=crossreftools_driver.tex}




\clearpage
\part{Meta information}

\section{Acknowledgements} \label{section::acknowledgements}

I would like to thank Javier Bezos to pointing me out to an issue with \refCom{crtcrefnumber} when being used as counter value extracting and inserting it again into \cs{setcounter} or any other occurence where a number value is expected. 

This issue is regarded fixed with \refCom{crtcrefcountervalue}. 


\section{Version history}


\begin{itemize}[itemsep=15pt]

\item \CHDocFullVersion{0.9} 

  Fixed bug in \cs{crtaddlabeltotoc} macro -- it clashed in expansion contexts. 

  
  Thanks to user \texttt{muzimuzhi-z} from \url{https://tex.stackexchange.com} who provided the bug fix in his answer to 
  \url{https://tex.stackexchange.com/questions/554100/crossreftools-docliccense-gives-error-with-restatement-of-restatable-theorem}

\item \CHDocFullVersion{0.9} 

  Fixed bug in \refCom{crtCref} macro -- it didn't show the reference number.



\item \CHDocFullVersion{0.8} 

  Added \refCom{crtcrefcountervalue}, see \cref{section::acknowledgements} for some explanation. 

\item \CHDocFullVersion{0.7} 

  Corrected two typos in \refCom{crtcref} and \refCom{crtCref}, leading to wrong reports of reference numbers. 

\item \CHDocFullVersion{0.6} 
  \begin{itemize}
    \item Corrected the typo in this manual about \refCom{crtifdefinedlabel} and \refCom{crtifundefinedlabel}
    \item Added the macros \refCom{crtlnameref} and \refCom{crtunameref} for providing a lower and upper case version of the first character in a \cs{nameref} - like usage.  
     \item Provided the convenience wrappers \refCom{crtnameref} and \refCom{crtnameref*} in order to make code compilable if \CHDocPackage{hyperref} is not loaded. 
  \end{itemize}

\item \CHDocFullVersion{0.5} 
  \begin{itemize}
    \item Added the \texttt{cleverefcompat} option. 
    \item Changed the internal code of \refCom{crtcrefpage} which was necessary after the update of \CHDocPackage{cleveref} to version 0.21
    \item Added some macros that check for label existence, see \cref{sec:checkinglabelexistence} about this. 
\end{itemize}

\item \CHDocFullVersion{0.4} 
  \begin{itemize}
    \item Corrected typos in this documentation
    \item Added the \CHDocTag{List of Labels} feature and the relevant macros from \cref{section::listoflabels}.
    \item Added the \texttt{final} and \texttt{draft} package options. 
    \item Introduced more generic label content macros. 
\end{itemize}
\item \CHDocFullVersion{0.3} 

Added the extraction macros for regular labels (i.e. not the \CHDocPackage{cleveref} - related ones) and convenience wrappers for generating links. 
\item \CHDocFullVersion{0.2} 

Introduced a check in \refCom{crtcrefnamebylabel} and \refCom{crtCrefnamebylabel} whether given label exists
\item   \CHDocFullVersion{0.1} 

First version
\end{itemize}


\printindex

\end{document}