From 8dc98ca4418ae3272e7b4e290443b6b424cb1eb5 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 31 Oct 2017 21:23:41 +0000 Subject: crossreftools (31oct17) git-svn-id: svn://tug.org/texlive/trunk@45657 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/crossreftools/README | 5 +- .../doc/latex/crossreftools/crossreftools_doc.pdf | Bin 181760 -> 196192 bytes .../doc/latex/crossreftools/crossreftools_doc.tex | 145 +++++++++++++++--- .../latex/crossreftools/crossreftools_driver.pdf | Bin 85475 -> 85058 bytes .../latex/crossreftools/crossreftools_driver.tex | 29 +++- .../tex/latex/crossreftools/crossreftools.sty | 167 +++++++++++++++++++-- 6 files changed, 315 insertions(+), 31 deletions(-) diff --git a/Master/texmf-dist/doc/latex/crossreftools/README b/Master/texmf-dist/doc/latex/crossreftools/README index abe74c12672..fd5fb45c6a5 100644 --- a/Master/texmf-dist/doc/latex/crossreftools/README +++ b/Master/texmf-dist/doc/latex/crossreftools/README @@ -1,4 +1,4 @@ -%% LaTeX package crossreftools - version 0.2 (2017/10/25 -- 23:08:36) +%% LaTeX package crossreftools - version 0.3 (2017/10/31 -- 08:23:52) %% README file for crossreftools.sty %% %% @@ -20,6 +20,7 @@ %% -The package crossreftools provides a way of extracting information for labels when the package cleveref is used. The macros are expandable. +The package crossreftools provides a way of extracting information for labels, also for special information stored by the package cleveref is used. The macros are expandable. + diff --git a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.pdf b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.pdf index 445f6391dce..22a83063e81 100644 Binary files a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.pdf and b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.pdf differ diff --git a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.tex b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.tex index e24b34656bc..b0f297be8f0 100644 --- a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.tex +++ b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_doc.tex @@ -1,4 +1,4 @@ -%% LaTeX package crossreftools - version 0.2 (2017/10/25 -- 23:08:36) +%% LaTeX package crossreftools - version 0.3 (2017/10/31 -- 08:23:52) %% Documentation file for crossreftools.sty %% %% @@ -79,6 +79,8 @@ \@namedef{crossreftoolsversion0.2}{v0.2 2017-10-25} +\@namedef{crossreftoolsversion0.3}{v0.3 2017-10-29} + \newcommand{\authorname}{Autor} @@ -300,7 +302,6 @@ \usepackage[T1]{fontenc} \usepackage{graphicx}% -\usepackage{crossreftools} \usepackage{amsmath} @@ -314,9 +315,12 @@ \usepackage{cleveref} -\def\packageversion{0.2} +\def\packageversion{0.3} + +\def\hyperrefversionwithfifthargument{v6.85a} + \usepackage{url} \setcounter{tocdepth}{3} @@ -347,9 +351,15 @@ pdfcreator={LaTeX} } +% Load here! + +\AtEndPreamble{ + \usepackage{crossreftools} +} \begin{document} + \yyyymmdddate @@ -359,7 +369,7 @@ -\CHPackageTitlePage[packageauthor={Christian Hupfer}]{Expandable extraction of cleveref data} +\CHPackageTitlePage[packageauthor={Christian Hupfer}]{Expandable extraction of cleveref and other label data} \clearpage @@ -381,9 +391,9 @@ \section*{Preface} -This package provides expandable extraction of information stored in labels generated with \CHDocPackage{cleveref}. +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, none of those are expandable and can not be used in an \cs{edef} - approach. +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 |\PackageDocName| @@ -398,7 +408,7 @@ Most times class and package authors will benefit of this package, but there mig 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 not load \CHDocPackage{cleveref} itself. +No packages are loaded by \CHDocPackage{crossreftools}, this package does neither load \CHDocPackage{hyperref} nor \CHDocPackage{cleveref} itself. \subsection{Loading of the package} @@ -423,6 +433,57 @@ As of \packageversion\ this package cannot be used with plain \TeX\ \parttoc +\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={\chdocextractversion{crossreftoolsversion0.3}}]{crtcrefpage}{\marg{label name}} + +This extracts the page number that would be printed by \cs{pageref}. +\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 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} + + + \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 @@ -460,7 +521,7 @@ would generate both the labels \verb!foo! and \verb!foo@cref!. The \CHDocPackage \CHDocPackage{\PackageDocName} extracts those properties with \refCom{crtextractcref}. \begin{docCommand}[code={\CHDocExpCommand{}}, -doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtextractcref}{\marg{property}\marg{labelname}} +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} @@ -468,32 +529,32 @@ This command will extract one of the properties \texttt{counter}, \texttt{number For convenience, there are shortcuts to extract a specific property: \begin{docCommand}[code={\CHDocExpCommand{}}, -doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefcounter}{\marg{labelname}} +doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefcounter}{\marg{label name}} -This extracts the counter belonging to a certain labelname. +This extracts the counter belonging to a certain label name. \end{docCommand} \begin{docCommand}[code={\CHDocExpCommand{}}, -doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefnumber}{\marg{labelname}} +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 labelname. +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.1}}]{crtcrefresult}{\marg{labelname}} +doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefresult}{\marg{label name}} -This extracts the result of the splitting of a counter belonging to a certain labelname. +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{labelname}} +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}}]{crtcrefpage}{\marg{labelname}} +doc new={\chdocextractversion{crossreftoolsversion0.1}}]{crtcrefpage}{\marg{label name}} This extracts the page number that would be printed by \cs{pageref}. \end{docCommand} @@ -501,6 +562,8 @@ This extracts the page number that would be printed by \cs{pageref}. \section{Additional macros and utilities} +\subsection{Expandable Commands} + \CHDocPackage{\PackageDocName} provides some expandable helper macros in order to query the cross reference names that are stored with \cs{crefname} and \cs{Crefname} from \CHDocPackage{cleveref}. \begin{docCommand}[code={\CHDocExpCommand{}}, @@ -530,18 +593,63 @@ This extracts the upper case cross reference plural name of a given counter. \begin{docCommand}[code={\CHDocExpCommand{}}, doc new and updated={\chdocextractversion{crossreftoolsversion0.1}}{\chdocextractversion{crossreftoolsversion0.2}}] -{crtcrefnamebylabel}{\marg{labelname}} +{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{labelname}} +{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{crtcref}. +\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{crtcref}. +\end{docCommand} + + + \clearpage \part{Examples} @@ -556,6 +664,7 @@ This extracts the upper case cross reference name of a given label. \begin{itemize}[itemsep=15pt] +\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} diff --git a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.pdf b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.pdf index 6b8abd73ee1..ef7b8cf627a 100644 Binary files a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.pdf and b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.pdf differ diff --git a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.tex b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.tex index 5150f4d96e4..38c5858af4d 100644 --- a/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.tex +++ b/Master/texmf-dist/doc/latex/crossreftools/crossreftools_driver.tex @@ -1,4 +1,4 @@ -%% LaTeX package crossreftools - version 0.2 (2017/10/25 -- 23:08:36) +%% LaTeX package crossreftools - version 0.3 (2017/10/31 -- 08:23:52) %% Driver file for crossreftools.sty %% %% @@ -21,12 +21,13 @@ \documentclass{book} -\usepackage{crossreftools} \usepackage{hyperref} \usepackage{cleveref} +\usepackage{crossreftools} + \setlength{\parindent}{0em} @@ -52,6 +53,26 @@ The result is \fbox{\crtcrefresult{\labeltoshow}} \edef\labeltoshowname{\crtcrefname{chapter}} +\section{Extracting usual reference information} + +Extracting content with \verb!\crtextractref! + \begin{itemize} + \item reference: \crtextractcref{reference}{\labeltoshow} + \item page: \crtextractcref{page}{\labeltoshow} +\end{itemize} + +If the \fbox{hyperref} package is loaded, further properties are retrievable: + +\begin{itemize} + \item name: \crtextractref{name}{\labeltoshow} + \item hyperanchor: \crtextractref{anchor}{\labeltoshow} + \item unused: \crtextractref{unused}{\labeltoshow} + \end{itemize} + +The 5th (and usually empty) label property introduced by hyperref is unused as of version v6.85a of that package -- \crtextractref{unused}{labelname} will return nothing here, i.e. the expansion is empty. + + + \section{Extracting the cleveref names} \begin{itemize} @@ -69,6 +90,10 @@ The result is \fbox{\crtcrefresult{\labeltoshow}} The macro \verb!\crtextractcref! is expandable!\edef\counterof{\crtextractcref{counter}{\labeltoshow}} Using the stored value for counter: \counterof! + +See \crthyperCref{fooequationlabel} + + \chapter{This is foo}\label{foochapterlabel} \setcounter{section}{5} diff --git a/Master/texmf-dist/tex/latex/crossreftools/crossreftools.sty b/Master/texmf-dist/tex/latex/crossreftools/crossreftools.sty index 93bee4fbf2c..10ec71fb078 100644 --- a/Master/texmf-dist/tex/latex/crossreftools/crossreftools.sty +++ b/Master/texmf-dist/tex/latex/crossreftools/crossreftools.sty @@ -1,4 +1,4 @@ -%% LaTeX package crossreftools - version 0.2 (2017/10/25 -- 23:08:36) +%% LaTeX package crossreftools - version 0.3 (2017/10/31 -- 08:23:52) %% Source file for crossreftools.sty %% %% @@ -19,21 +19,17 @@ %% %% -\def\crossreftoolspackageversion{0.2} +\def\crossreftoolspackageversion{0.3} \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{crossreftools}[2017/10/25 - v\crossreftoolspackageversion] +\ProvidesPackage{crossreftools}[2017/10/31 - v\crossreftoolspackageversion] % Some helper macros -\newcommand{\crt@firstoffive}[5]{#1} \newcommand{\crt@refundefined}{[UNDEFINED]} -\long\def\crt@gobblethree#1#2#3{} -\long\def\crt@gobbletwo#1#2{} -\long\def\crt@gobbleone#1{} -% Splitters +% Splitters for cleveref \def\crt@@cref@@splitter@@first[#1][#2][#3]#4\@nil{% #1% @@ -121,7 +117,7 @@ \expandafter\ifx\csname r@#2@\@@crt@@cref@@suffix\endcsname\relax \crt@refundefined% \else - \expandafter\expandafter\expandafter\expandafter\expandafter\csname crt@cref@splitter@#1\expandafter\endcsname\csname r@#2@cref\endcsname% + \expandafter\expandafter\expandafter\expandafter\expandafter\csname crt@cref@splitter@#1\expandafter\endcsname\csname r@#2@\@@crt@@cref@@suffix\endcsname% \fi } @@ -151,5 +147,158 @@ } +%%%%% + +% Default cref format + +\newcommand{\crtcref}[1]{% + \expandafter\ifx\csname r@#1\endcsname\relax + \crt@refundefined% + \else + \crtcrefnamebylabel{#1} \crtcrefnumber{#1}% + \fi +} + +\newcommand{\crtCref}[1]{% + \expandafter\ifx\csname r@#1\endcsname\relax + \crt@refundefined% + \else + \crtCrefnamebylabel{#1} \crtcrefnumber{#1}% + \fi +} + + +% refcount - like support + + +\newif\if@crt@hyperrefloaded + + +\@ifpackageloaded{hyperref}{\global\@crt@hyperrefloadedtrue}{} + + +\AtBeginDocument{% + \if@crt@hyperrefloaded + \def\crt@@ref@@splitter@@first#1#2#3#4#5\@nil{% + #1% + } + + \def\crt@@ref@@splitter@@second#1#2#3#4#5\@nil{% + #2% + } + + \def\crt@@ref@@splitter@@third#1#2#3#4#5\@nil{% + #3% + } + + \def\crt@@ref@@splitter@@fourth#1#2#3#4#5\@nil{% + #4% + } + + \def\crt@@ref@@splitter@@fifth#1#2#3#4#5\@nil{% + #5% + } + \else + % No hyperref + \def\crt@@ref@@splitter@@first#1#2\@nil{% + #1% + } + + \def\crt@@ref@@splitter@@second#1#2\@nil{% + #2% + } + + \def\crt@@ref@@splitter@@third#1#2\@nil{% + % Nothing for convenience + } + + \def\crt@@ref@@splitter@@fourth#1#2\@nil{% + % Nothing for convenience + } + + \def\crt@@ref@@splitter@@fifth#1#2\@nil{% + % Nothing for convenience + } + \fi +} + + \def\crt@ref@splitter@firstarg#1{% + \expandafter\crt@@ref@@splitter@@first#1\@nil% + } + + \def\crt@ref@splitter@secondarg#1{% + \expandafter\crt@@ref@@splitter@@second#1\@nil% + } + + \def\crt@ref@splitter@thirdarg#1{% + \expandafter\crt@@ref@@splitter@@third#1\@nil% + } + + \def\crt@ref@splitter@fourtharg#1{% + \expandafter\crt@@ref@@splitter@@fourth#1\@nil% + } + + \def\crt@ref@splitter@fiftharg#1{% + \expandafter\crt@@ref@@splitter@@fifth#1\@nil% + } + + +\newcommand{\@@crtextr@ct@ref}[2]{% + \expandafter\ifx\csname r@#2\endcsname\relax + \crt@refundefined% + \else + \expandafter\expandafter\csname crt@ref@splitter@#1\endcsname\csname r@#2\endcsname% + \fi +} + +\let\crt@ref@splitter@reference\crt@ref@splitter@firstarg +\let\crt@ref@splitter@page\crt@ref@splitter@secondarg +\let\crt@ref@splitter@name\crt@ref@splitter@thirdarg +\let\crt@ref@splitter@anchor\crt@ref@splitter@fourtharg +\let\crt@ref@splitter@unused\crt@ref@splitter@fiftharg + + +\newcommand{\crtextractref}[2]{% + \@@crtextr@ct@ref{#1}{#2}% +} + + +\newcommand{\crtrefnumber}[1]{% + \@@crtextr@ct@ref{reference}{#1}% +} + + +\newcommand{\crtrefpage}[1]{% + \@@crtextr@ct@ref{page}{#1}% +} + +\newcommand{\crtrefanchor}[1]{% + \@@crtextr@ct@ref{anchor}{#1}% +} + +\newcommand{\crtrefname}[1]{% + \@@crtextr@ct@ref{name}{#1}% +} + +%%% Hyperref wrappers, not expandable. + + +\newcommand{\crthyperlink}[2]{% + \if@crt@hyperrefloaded + \hyperlink{#1}{#2}% + \else + #2% + \fi +} + +\newcommand{\crthypercref}[1]{% + \crthyperlink{\crtrefanchor{#1}}{\crtcref{#1}}% +} + +\newcommand{\crthyperCref}[1]{% + \crthyperlink{\crtrefanchor{#1}}{\crtCref{#1}}% +} + + \endinput -- cgit v1.2.3