% \iffalse meta-comment
%% =============================================================================================
%
% Copyright 2009 J. Niel de Beaudrap.
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% 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.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
% ^^A -*-LaTeX-*-
%
% ^^A These shouldn't come out in .ist files, hence the module
% ^^A comments, or in the printed version, hence temporary comment
% ^^A category for `<'
%\catcode`\<=14
%<+package>\def\basename{modref}
%<+package>\def\fullname{restyle: cross-referencing hacks for LaTeX}
%<+package>\def\revisiondate{2009/02/02}
%<+package>\def\revision{0.9}
%<+package>\def\writtenby{J. Niel de Beaudrap}
%\catcode`\<=12
%
% \CheckSum{0}
%% \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 \~}
%%
%\iffalse This is a METACOMMENT
% Everything up to the next `\ fi' (without a blank) will
% be ignored. This is necessary because `%' may no longer
% be a comment mark when this file is read in.
%
%% Package `modref' to use with LaTeX 2e
%% Copyright (C) 2007 J. Niel de Beaudrap, all rights reserved.
%
%
% Version: Date: Changes:
%
% 1.0 First revision.
%
% \changes{v1.0}{2007/12/16}{First revision.}
%\fi
%
% \setcounter{StandardModuleDepth}{1}
%
% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
% \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign
%
% \newcommand\ModRef{\texttt{modref}}
%
% \GetFileInfo{modref.sty}
%
% \iffalse
% =============================================================================================
% \fi
%\catcode`\<=14
%<+package>\typeout{-------}
%<+package>\typeout{\fullname \space v\revision \space(\basename)}
%<+package>\typeout{\writtenby, \revisiondate}
%<+package>\typeout{-------}
%<+package>\ProvidesPackage{modref}[\revisiondate {} {v\revision} {\writtenby}]
%<+package>\RequirePackage{kvoptions}
%<+package>
%<+package>\DeclareOption*{\PackageWarning{Unknown option `\CurrentOption'.}}
%<+package>\makeatletter
%\catcode`\<=12
% \iffalse
% =============================================================================================
% \fi
%\iffalse
%<*driver>
\documentclass[draft]{ltxdoc}
\usepackage[left=4.5cm,right=3cm,top=3cm,bottom=3cm]{geometry}
\usepackage{amsmath,amsthm}
\usepackage{modref}
% \EnableCrossrefs
% \DisableCrossrefs % Say \DisableCrossrefs if index is ready
% \CodelineIndex
% \RecordChanges % Gather update information
% \OnlyDescription % comment out for implementation details
% \OldMakeindex % use if your MakeIndex is pre-v2.9
\setlength\hfuzz{15pt} % dont make so many
\hbadness=7000 % over and under full box warnings
\refstyle{itemNo}{[Item~\##1]}
\refstyle{numero}{\texttt{\itshape numero~#1}}
\refstyle{def}{Definition~#1}
\refstyle{lemma}{Lemma~#1}
\refstyle{thm}{Theorem~#1}
\refstyle{fig}{Figure~#1}
\refstyle{eqn}{Eqn.~#1}
\eqrefstyle{\textbf{(#1)}}
\displaytagstyle{{\Large$\bigcirc\mspace{-12mu}$}#1}
\stepcounter{equation}
\makeatletter
\newenvironment{headerlist}{%
\setlength\topsep{\baselineskip}%
\setlength\parsep{1.3em}%
\setlength\parskip{1.3em}%
\setlength\listparindent{0ex}%
\def\next@item[##1]{%
\def\item{\egroup\next@item}
\@inmatherr\item
\bgroup
\addtolength\leftskip{2.5em}%
\par\noindent\hspace{-2.5em}\mbox{\headerliststyle{##1}}~\\[1ex]%
\setlength\parindent{0ex}%
\setlength\parskip{1ex}%
\ignorespaces}
\let\item\next@item
}{%
\par\egroup\leavevmode\noindent\ignorespaces
}
\newcommand\headerliststyle[1]{\texttt{\mdseries\upshape #1}}
\makeatother
\newcommand\ie{\textit{i.e.}}
\newcommand\eg{\textit{e.g.}}
\newcommand\etc{\textit{etc.}}
\begin{document}
\DocInput{modref.dtx}
\end{document}
%</driver>
% \fi
%
% \DeleteShortVerb\|
% \MakeShortVerb\"
%
% \makeatletter
% \newenvironment{codeexample}[1][rm]
% {\[ \mspace{10mu}\begin{minipage}{0.95\textwidth} \def\@tempa{#1} \begin{\@tempa}}
% {\end{\@tempa} \end{minipage} \\[-1em] \]}
%
% \def\lt{<}
% \catcode`\<=13
% \def\@less@char{<}
% \expandafter\def\@less@char#1>{$\left\langle \textrm{\mdseries\itshape #1} \right\rangle$}
% \makeatother
% \newcommand\descr[1]{<\textit{#1}>}
% \newcommand\op[1]{\mathrm{#1}} ^^A %\mathop{\operator@font #1}}
%
% \newcommand\DescribeOption[1]{\DescribeMacro{option:\;#1}}
% \newenvironment{option}[1]{\begin{environment}{option:\;#1}}{\end{environment}}
%
%
% \iffalse
% =============================================================================================
% \fi
%
% \title{The \ModRef\ Package\thanks
% {This file has version number \fileversion{} dated \filedate{}.}}
% \author{Niel de Beaudrap}
%
% \maketitle
%
% \begin{abstract}
% This package defines some hacks to allow authors to define customized output
% for cross-references of different types, based on the reference label.
% \end{abstract}
%
% \section{The purpose and overview of \ModRef}
%
% Usually, when labelling equations, definitions, figures, \etc\ in a document, experienced authors will give their
% labels intelligent names indicating the kind of reference, such as "eqn:quadratic", "def-integral", "fig.instrument-layout",
% or similar labels.
% In the course of using cross-references, the author will then proceed to repeatedly write same text to accompany each instance
% of these labels throughout their document, as in the following examples:
% \begin{verbatim}
% Theorem~\ref{thm:fundmental-calculus}
% Theorem~\ref{thm:intermediate-value}
% Theorem~\ref{thm:four-colour}
%
% Definition~\ref{def:hilbert-space}
% Definition~\ref{def:delta-dirac}
%
% Figure~\ref{fig:instrument-layout}
% Figure~\ref{fig:experimental-data}
% Figure~\ref{fig:nine-hundred-billion}
% Figure~\ref{fig:newton}
% \end{verbatim}
% \vspace{-\baselineskip}
% and so on.
% Given that the references are retrieved from the values of counters written to the auxiliary file, one solution might be to
% redefine the relevant counters, \eg\ as in
% \begin{verbatim}
% \renewcommand\thetheorem{Theorem~\arabic{theorem}}
% \end{verbatim}
% \vspace{-\baselineskip}
% but it is occasionally still desirable to retrieve the reference without the title, as when referring to multiple similar references,
% such as
% \begin{verbatim}
% Theorems~\ref{thm:foo} and~\ref{thm:bar}
% \end{verbatim}
% \vspace{-\baselineskip}
% so that a simple strategy of redefining "\thetheorem" is inadequate.
% More sophisticated approaches involving redefining how counters are written to the auxiliary file will also produce problems, \eg
% when one counter ``counts within'' another: for instance, if theorem numbers are of the format "\thechapter-\arabic{theorem}", the
% theorem label would also inherit the labelling of the chapter reference (which is unproductive).
%
% However, if the document author names reference labels in a literate manner, it is possible to automate the production
% of the accompanying text by scanning those reference labels, in a way totally independent of how the counter is defined, and
% in a way which does not affect how the reference is recorded in the auxiliary file.
% It is only necessary to allow the formatting to vary somehow depending on the label.
% However, as not everyone uses the same labelling scheme for their cross-references, the way in which reference-labels map
% to reference-formatting should be fairly flexible.
%
% The \ModRef\ package provides the functionality to easily define customized output for the \cmd\ref\ command by
% identifying what sort of cross-reference is being made, based on an initial string of characters in the reference label.
% This functionality is provided in a transparent manner, in that only changes the output of \cmd\ref\ for those cases
% defined by the user, and the way in which those references are formatted is also specified by the user.
% It also provides a way for authors to perform more powerful tasks, such as having every reference produce a margin note
% in a completely customizable fashion, and easy customization of the appearance of displayed equation numbers in "amsmath"
% environments.
%
% \subsection{Comparison with \texttt{fancyref}}
%
% Similar functionality to what \ModRef\ provides has been available since 1999 in the "fancyref" package.\footnote{^^A
% The core functionality of \ModRef\ was developped independently of "fancyref": my sense of whether someone would have done
% the same task before failed me in this instance, and I discovered the package after having implemented the commands
% \cmd\refstyle, \cmd\setrefdelimiter, and an earlier version of \cmd\eqrefstyle\ (not to mention most of this document).
% However, much of the functionality of this package as it exists currently was prompted by ideas derived from "fancyref".}
% The functionality provided by \ModRef\ differs from that of "fancyref" in the following ways:
% \begin{itemize}
% \item
% The syntax for defining new reference styles is simpler: \ModRef\ does not require the author provide a macro in which
% to store each new reference style.
%
% \item
% Authors can also use \ModRef\ to define top-level reference customization which is applied to all well-formed
% references in a \emph{general} way, using the customized cross-references and the page-number of the reference as arguments,
% using similar syntax to defining any other macro.
% (The "fancyref" package enables putting all references in parentheses, putting references in margin-notes, and including
% page-numbers \emph{\`a la} "varioref" in all references; the documentation also advertises customizable hooks.)
%
% \item
% The behaviour of \cmd\ref\ is changed to use the customized reference behaviour.
% (Purists who find this distasteful but who still with to use \ModRef\ --- or any user who just wishes to access the
% original functionality of \cmd\ref\ --- can find the original behaviour retained in the macro \cmd\Ref.)
%
% \item
% The \ModRef\ package also enables the customization of displayed equation tags, and of the output of the command \cmd\eqref,
% as defined by the "amsmath" package.
% \end{itemize}
% However, the main distinction between \ModRef\ and "fancyref" is in the design philosophy:
% \begin{itemize}
% \item[---]
% "fancyref" appears to have been written in an attempt to anticipate anything that an author might wish to do: therefore, it
% has a great many redundant pre-defined macros, which one may change to achieve varying degrees of change from the default
% configuration;
%
% \item[---]
% \ModRef\ was written to have a simple interface for customizing references, without many assumptions about how an author
% might wish to customize their references (except that it be not too tedious): any changes defined by an author are relative to
% the default behaviour of \LaTeX.
% \end{itemize}
% It is my hope that, as a result of the above differences, \ModRef\ will prove to be a convenient choice for authors who wish to
% customize how cross-references appear in their documents.
%
% \subsection{Functionality provided by \ModRef}
%
% The \ModRef\ package introduces the following concepts, and access to control how these concepts are applied to
% cross-references in documents.
% \begin{headerlist}
% \renewcommand\headerliststyle[1]{\textrm{\mdseries\itshape #1}}
%
% \item[Special reference styles]
% A ``special'' reference style is a command which is performed on references of a certain type.
% What command is performed depends on the type of the reference; and the type of any reference is determined from its label.
%
% The author defines one or more styles by specifying a ``prefix'' or ``style name'' for each style --- such as ``"dfn"'' for
% definitions, ``"eq"'' for equations, \etc\ --- and describes the formatting to be applied for that reference type.
% For each reference, \ModRef\ then attempts to determine the type of the reference by matching the label against known
% style names.
% The name is delimited by default using a colon (``":"'') character (but the delimiter may be chosen by the author, and
% even changed mid-document): thus, an equation reference might have a label such as ``"eq:quadratic"'', a definition might have
% a label ``"dfn:vectorSpace"'', and so on.
%
% The result of applying a reference style to a particular type of reference is a \emph{customized reference}.
% Any reference whose label does not contain a defined reference type has no special style applied to it.
%
% The command to use to define special reference styles is \cmd\refstyle; the command to change the delimiter mid-document is
% \cmd\setrefdelimiter.
% (There is also a package option "delimiter" which allows the delimiter to be set at the beginning of the document.)
%
% \item[Global reference styles]
% A ``global'' reference style is a command which is performed at \emph{every} reference.
% Only two global reference styles may be defined for a given document: a default one and a ``variant'' one.
% The inputs to a global reference style are the customized reference (if the reference is of a particular type) and the page number;
% authors are free to use these arguments however they wish to define the behaviour of the \cmd\ref\ function.
% Initially, the behaviour is just to pass on the (possibly customized) reference unchanged, omitting the page number.
%
% The commands to define the global reference styles are \cmd\GlobalRefStyle\ and \cmd\GlobalVarRefStyle; the commands
% which apply the two different reference styles are \cmd\ref\ and \cmd\varref.
%
% \item[Equation references and displayed equation tags]
% There is exactly one exception to the above description of how references are customized: if the author uses the "amsmath"
% package, the output of the command \cmd\eqref\ remains \emph{totally unmodified} --- unless, of course, they wish to modify it;
% then \ModRef\ facilitates doing this.
%
% Because the output of \cmd\eqref\ is by design intended to be different from that of \cmd\ref, global reference styles
% are never applied to any application of \cmd\eqref.
% As well, \cmd\eqref\ is never defined to attempt to infer the type of a reference from its label (presumably, it's an equation).
% However, \ModRef\ does allow different reference styles to be defined for \cmd\eqref.
%
% While we're customizing cross-references to equations, why not allow how the equations themselves are labelled to be customized?
% This allows the author to fine-tune the appearance of equation tags.
% However, these customizations do not affect the output of \cmd\eqref, or vice-versa.
%
% The command to redefine the behaviour of \cmd\eqref\ is \cmd\eqrefstyle; the command to redefine how equation numbers
% appear in displayed equations is \cmd\displaytagstyle.
%
%^^A \item[Cross-references without styles]
%^^A It is possible to access the original functionality of \cmd\ref\ in the macro \cmd\Ref.
% \end{headerlist}
% \hspace{-2\baselineskip} No special reference styles are pre-defined by \ModRef, and no global styles are defined (except
% for the ``trivial'' styles described above); only the reference-styles which the document author defines will be applied.
%
% \subsection{Package options}
%
% This version of \ModRef\ has the following option:
%
% \begin{headerlist}
% \item[delimiter=<string>]
% This option controls the string which delimits the prefix defining the type of a particular reference.
% If omitted, the default value is a single colon character (``":"'').
% This string may be set to any value, except \textbf{(a)}~the empty string, \textbf{(b)}~any string containing a comma,
% or \textbf{(c)}~any string containing characters not allowed in package options by \LaTeX\ (\eg\ ``"{"'', ``"}"'', \etc)
% \end{headerlist}
% \vspace{-2\baselineskip}
%
% \subsection{Package dependencies/conflicts}
%
% The package \ModRef\ depends on the "kvoptions" package, which should be included in modern \LaTeXe\ distributions.
% It is currently incompatible with the "hyperref" package: compatibility is planned for the next version.
%
% \subsection{Bugs}
%
% There are no known bugs in \ModRef.
%
% \iffalse
% =============================================================================================
% \fi
%
% \section{How to use \ModRef}
%
% The \ModRef\ package is very simple.
% The user interface essentially consists of two commands: the invocation "\usepackage{modref}" itself (which currently
% accepts three options), and the command \cmd\refstyle; a few other macros are provided to perform auxiliary functions.
% We will describe these in the opposite order.
%
% \subsection{Defining reference styles}
% \label{numero:definingModRefs}
%
% \subsubsection*{Special reference styles}
%
%^^A The \ModRef\ package functions by redefining the command \cmd\ref\ in such a way as to interpret the cross-reference labels
%^^A provided to it.
%^^A Depending on an initial prefix --- which we will variously call a ``label prefix'' or ``style name'' --- it will then apply
%^^A an author-defined style if one has been defined for the particular type of reference.
%
% \DescribeMacro{\refstyle}
% Special reference styles can be defined for different label-prefixes using the \cmd\refstyle\ macro, which has the syntax:
% \begin{center}
% "\refstyle{"\textit{style-name}"}{"\textit{style-format}"}"
% \end{center}
% which defines a style with the given style-name.
% (The reason for the mixed-
% The style-format is a macro definition is a similar to what is used for \cmd\def\ and \cmd\newcommand, using at most a single
% argument.
% The value of that single argument should be interpreted as the \emph{usual} output of the \cmd\ref\ command: \ie\
% style-formats are descriptions of transformations to perform on ``ordinary'' cross-references.
%
% The \cmd\refstyle\ command can be used multiple times for a single reference-style in order to override previous definitions
% of the style-formats for that style; however, it is recommended only to use it in the pre-amble to avoid confusion.
%
% \paragraph{Use cases.}
% The effects of using \cmd\refstyle\ can be demonstrated as follows.
% \begin{enumerate}
% \item
% \label{firstitem}
% Style-names are identified from cross-reference labels by looking for a label-prefix, separated from the rest of the label
% by a delimiter such as a colon (":") character.
% For any cross-reference label which does not have such a delimiter, such as "genericlabel", the usual behaviour of \cmd\ref\
% applies.
%
% \textbf{Example.}
% This list item is labelled with the command "\label{firstitem}".
% This label doesn't contain an identifiable label-prefix, so "\ref{firstitem}" produces the output \ref{firstitem}, as usual.
% As well, this document doesn't have a cross-references labelled "undef-reference"; therefore, "\ref{undef-reference}"
% produces the output \ref{undef-reference}, as usual.
%
% \item
% \label{item:second}
% If a cross-reference label has an identifiable prefix, but this prefix does not correspond to a defined style-format, the
% usual behaviour of \cmd\ref\ applies as well.
%
% \textbf{Example.}
% This second list item is labelled with the command "\label{item:second}".
% However, this document didn't define any style-name called ``"item"''; therefore, "\ref{item:second}" produces the output
% \ref{item:second}.
%
% \item
% \label{itemNo:third}
% If a cross-reference label has an identifiable prefix which does correspond to a style-format, the style-format is applied
% to the cross-reference.
%
% \textbf{Example.}
% In the header of this document, the following reference style was defined:
% \begin{verbatim}
% \refstyle{itemNo}{[Item~\##1]}
% \end{verbatim}
% The label for this list item was defined using "\label{itemNo:third}".
% Because the usual meaning of "\ref{itemNo:third}" would be \Ref{itemNo:third}, the resulting output of "\ref{itemNo:third}"
% is \ref{itemNo:third}.
%
% \item
% \label{numero:fourth}
% The style-formats do not correspond in any way to individual counters, but only to the labels given to the references.
% Thus, references which use the same counter may be given different styles, if this is a meaningful thing to do, simply by
% making the label prefixes different; and references with different counters may be given the same reference style.
%
% \textbf{Example.}
% In the header of this document, the following reference style was defined:
% \begin{verbatim}
% \refstyle{numero}{\texttt{\itshape numero~#1}}
% \end{verbatim}
% The label for this list item was defined using "\label{numero:fourth}": this gives rise to a different format of reference
% than the reference style ``"itemNo"'' --- in particular, "\ref{numero:fourth}" produces \ref{numero:fourth}.
% At the same time, the cross-reference label for this section is defined by "\label{numero:definingModRefs}"\,: thus,
% "\ref{numero:definingModRefs}" produces \ref{numero:definingModRefs}.
%
% \item
% The new implementation for \cmd\ref\ applies styles only to well-defined cross-references: that is, it acts as though the
% customized output is the entire cross-reference.
%
% \textbf{Example.}
% This document doesn't have any cross-reference "itemNo:undef-reference"; therefore, despite the fact that this
% label contains the style-prefix ``"itemNo"'', the reference "\ref{itemNo:undef-reference}" produces the output
% \ref{itemNo:undef-reference}, as with any ill-defined reference.
% \end{enumerate}
% A more coherent illustration of how to use \cmd\refstyle, and how it affects cross-references, is illustrated in \ref{fig:example}.
%
% \DescribeMacro{\eqrefstyle}
% The syntax of \cmd\eqrefstyle\ is similar: it takes a single argument, specifying the style for any cross-reference using \cmd\eqref.
% Global reference styles are not applied to uses of \cmd\eqref; and as with \cmd\ref, \cmd\eqref\ produces the output
% \eqref{undefined-reference} when applied to undefined references.
%
%
% \begin{figure}[t]
% \begin{center}
% \begin{minipage}{0.4\textwidth}
% \begin{verbatim}
% \refstyle{def}{Definition~#1}
% \refstyle{lemma}{Lemma~#1}
% \refstyle{thm}{Theorem~#1}
% \refstyle{eqn}{Eqn.~#1}
%
% \eqrefstyle{\textbf{#1]}}
% \displaytagstyle{{\Large%
% $\bigcirc\mspace{-12mu}$}#1}
%
% % Main text:
%
% \begin{definition}
% \label{def:lorentz} ...
% \end{definition}
%
% \begin{lemma}
% \label{lemma:simultaneity} ...
% \end{lemma}
%
% \begin{theorem}
% \label{thm:einstein} ...
% \begin{gather}
% \label{eqn:einstein}
% E = mc^2
% \end{gather}
% ...
% \end{theorem}
%
% \ref{thm:einstein} ...
% \eqref{eqn:einstein} ...
%
% \ref{def:lorentz} and
% \ref{lemma:simultaneity} ...
% \ref{eqn:einstein} ...
% \end{verbatim}
% \end{minipage}
% ~\vrule~~
% \begin{minipage}{0.44\textwidth}
% \newtheorem{lemma}{Lemma} \setcounter{lemma}{10}
% \newtheorem{theorem}{Theorem} \setcounter{theorem}{3}
%
% \theoremstyle{definition}
% \newtheorem{definition}{Definition}
% \setcounter{definition}{4} \renewcommand\thedefinition{\Roman{definition}}
%
% \begin{definition}
% \label{def:lorentz}
% A theory of physics is \emph{Lorentz invariant} if [\ldots]
% \end{definition}~\\[-1ex]
%
% \begin{lemma}
% \label{lemma:simultaneity}
% For two distinct events $A$ and $B$, there exists a reference frame in which they are simultaneous if \textup{[\ldots]}
% \end{lemma}~\\[-1ex]
%
% \begin{theorem}
% \label{thm:einstein}
% The equivalent mass $m$ which is associated with some amount of energy $E$ is determined by the equation
% \begin{gather}
% \label{eqn:einstein} E = mc^2
% \end{gather}
% where $c$ is the speed of light.
% \end{theorem}~\\[-1ex]
%
% \ref{thm:einstein} is actually a corollary of a more general theorem, which generalizes \eqref{eqn:einstein} by
% adding a dependency on momentum.\\
%
% \ref{def:lorentz} and \ref{lemma:simultaneity} are also important ideas forming part of the Special
% Theory of Relativity; but \ref{eqn:einstein} is its most famous formula.
% \end{minipage}
% \end{center}
% \caption{\label{fig:example}%
% Illustration of (some of) the functionality of \ModRef\ package.}
% \end{figure}
%
% \subsubsection*{Global reference styles}
%
% Two different global reference styles can be defined using the \cmd\GlobalRefStyle\ and \cmd\GlobalVarRefStyle\ macros,
% which have the syntax:
% \begin{center}
% \begin{minipage}{16em}\raggedright
% "\GlobalRefStyle{"\textit{style-format}"}" \\
% "\GlobalVarRefStyle{"\textit{style-format}"}"
% \end{minipage}
% \end{center}
% Again, the style-format is a macro definition, in this case using at most \emph{two} arguments.
% The operands of these two arguments are the (customized) cross-reference, and the page number of that reference: thus,
% the effect of a global reference style on a cross-reference might look something like
% \begin{center}
% \itshape"\GlobalStyleMacro"\upshape"{Definition~V}{13}"
% \end{center}
% for a definition on page thirteen, if definitions have been given a special reference style which inserts ``\,"Definition~"\,''
% at the beginning of every reference.\footnote{^^A
% No macro specifically named \textit{\cmd\GlobalStyleMacro} is defined by \ModRef; this example is only intended for
% illustrative purposes.}
%
% \DescribeMacro{\varref}
% The global style defined by \cmd\GlobalRefStyle\ is applied to every cross-reference made with \cmd\ref; the variant global
% style is applied for cross-references made with \cmd\varref.
% (This is the only difference between \cmd\ref\ and \cmd\varref: the functionality will be otherwise identical.)
%
% Initially, both of the global reference styles do nothing except discard the page number, similarly to how \cmd\ref\ usually works.
% In a typical application, it would be quite reasonable to leave the ``main'' global reference style unchanged, only to customize
% the ``variant'' style.
% For instance, one might sensibly choose to declare
% \begin{verbatim}
% \GlobalVarRefStyle{#1 (on page #2)}
% \end{verbatim}\vspace{-\baselineskip}
% to facilitate combining cross-referencing with page numbers, or
% \begin{verbatim}
% \GlobalVarRefStyle{(#1)}
% \end{verbatim}\vspace{-\baselineskip}
% to make it easy to turn a cross-reference into a parenthetical remark, in both cases by using \cmd\varref\ to perform the
% cross-reference.
%
% To avoid too much non-uniformity in the appearance of cross-references, neither \cmd\GlobalRefStyle\ nor \cmd\GlobalVarRefStyle\
% are allowed outside of the document pre-amble.
%
% \subsection{Other features}
%
% \subsubsection*{Customizing the delimiter for reference types}
%
% \DescribeMacro{\setrefdelimiter}
% In the examples above, the style-name was determined from cross-reference labels by scanning for the shortest substring at
% the beginning of the label which did not contain a ``\:\!":"\:\!'' character.
% However, authors can change this delimiter to any (non-empty) sequence of characters.
% This can be done at the beginning of the document by invoking the package as
% \begin{center}
% "\usepackage[delimiter="<string>"]{modref}"
% \end{center}
% or mid-document by using the command "\setrefdelimiter{"\textit{string}"}"; all subsequent uses of \cmd\ref\ or \cmd\varref\
% will attempt to discover reference types using the new delimiter.\footnote{^^A
% An immediate consequence of this is that references which previously had a defined ``reference type'' using the old delimiter
% may not have a defined type using the new delimiter.
% This will then have the effect of temporarily rescinding all special reference styles for those references using the old delimiter;
% the styles can be restored by restoring that delimiter.}
%
% \subsubsection*{Customizing tags in \texttt{amsmath}-style displayed equations}
%
% \DescribeMacro{\displaytagstyle}
% The style in which equation numbers are shown in the displayed-math environments defined by the "amsmath" package can be customized
% using the \cmd\displaytagstyle\ command, which again has similar syntax to \cmd\refstyle\ and \cmd\eqref:
% \begin{center}
% "\displaytagstyle{"\textit{style-format}"}"
% \end{center}
% This also has the more general effect of defining the style for the \cmd\tag\ command, which can be used to insert
% \emph{ad-hoc} equation tags in displayed math environments; the effect of the "\tag*" macro, however, is unaffected.
%
% \subsubsection*{Accessing the original functionality of \cmd\ref}
%
% \DescribeMacro{\Ref}
% Sometimes it is useful to access a cross-reference without any special formatting.
% To do this, one may use the \cmd\Ref\ command: this preserves the standard \LaTeXe\ functionality of \cmd\ref.
%
%^^A \paragraph{Example.}
%^^A Although both items~\Ref{itemNo:third} and~\Ref{numero:fourth} in Section~\Ref{numero:definingModRefs} --- and the
%^^A label for Section~\Ref{numero:definingModRefs} itself --- specify styles in their cross-reference labels (``"itemNo:third"'',
%^^A ``"numero:fourth"'', and ``"numero:definingModRefs"'' respectively), we can refer to them without the special reference styles
%^^A (as we did just above) by using the syntax "\Ref{itemNo:third}", "\Ref{numero:fourth}", and "\Ref{numero:definingModRefs}".
%
%
% \iffalse
% ==========================================================================================
% \fi
%
% \section{Implementation}
%
% \subsection{Preliminary definitions}
%
% \begin{macro}{\modref@error}
% First, we define a generic command "\modref@error" for producing errors.
% \begin{macrocode}
\newcommand\modref@error{\PackageError{modref}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Ref}
% As most of the subsequent definitions revolve around redefining aspects of the \cmd\ref\ command and friends,
% we define the command \cmd\Ref\ which preserves the original behaviour for reference.
% (If the macro \cmd\Ref\ is already defined, we produce an error.)
% \begin{macrocode}
\edef\reserved@a{Ref}%
\@ifundefined\reserved@a{%
\let\Ref\ref
}{%
\modref@error{%
Command \string\Ref\ defined already; refer to the help message.%
}{%
The "modref" package defines the command \string\Ref\ to allow you (and
the package) to use the original functionality of \string\ref. However, in
this instance, \string\Ref\ already had a meaning when "modref" started
running. Please determine what is defining \string\Ref, and whether you need
it.}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@ifempty}
% \begin{macro}{\@xifempty}
% We also crib the code for "\@ifempty" from "amsgen.sty" for simplicity.
% \begin{macrocode}
\def\@ifempty#1{\@xifempty#1@@..\@nil}
\long\def\@xifempty#1#2@#3#4#5\@nil{ %
\ifx#3#4\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Declaration and processing of the package options}
%
% Using the "kvoptions" package, we define the options for \ModRef, and the default value for the "fixtagsize" option.
% \begin{macrocode}
\DeclareStringOption[:]{delimiter}
\ProcessKeyvalOptions*
% \end{macrocode}
%
% \subsection{The core functionality, and customization of label delimiters}
%
% \begin{macro}{\setrefselimiter}
% The macro \cmd\setrefdelimiter\ is a meta-macro which takes a single argument: this argument will be used as a delimiter
% in further macros which define the infrastructure of \ModRef.
% \begin{macrocode}
\newcommand\setrefdelimiter[1]{%
% \end{macrocode}
% Throughout the following, "#1" denotes the delimiter to be used for identifying the style prefix in a cross-reference label.
% \begin{macro}{\ref}
% \begin{macro}{\varref}
% The replacement for \cmd\ref\ will pass its argument onto another macro \makeatletter\cmd\modref@ref\makeatother, which will
% attempt to parse the argument for a delimiter; we define \cmd\varref\ similarly.
% They each pass a macro (\makeatletter\cmd\modref@basestyle\makeatother\ and \makeatletter\cmd\modref@varbasestyle
% \makeatother, respectively) as a final argument, to define the ``global'' formatting which is to be used for the reference
% regardless of which particular reference style (if any) is to be used.
% We employ the standard strategy of appending a delimiter to the end of the argument, together with an unlikely terminal command
% sequence.
% \begin{macrocode}
\def\ref##1{\modref@ref##1#1\egroup\modref@basestyle}%
\def\varref##1{\modref@ref##1#1\egroup\modref@varbasestyle}%
% \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\modref@ref}
% The command \makeatletter\cmd\modref@ref\makeatother\ attempts to split the argument into a prefix, delimiter, and suffix.
% If the suffix is empty, the original argument to \cmd\ref\ had no delimiter (and thus indicates no style): in that case,
% \makeatletter\cmd\modref@ref\makeatother\ invokes \makeatletter\cmd\@setref\makeatother\ on the reference, using the global
% format specified in "##3" and the identity function as the ``style format''.
% Otherwise, it passes it on to a second macro \makeatletter\cmd\modref@@ref\makeatother\ for further processing.
% \begin{macrocode}
\def\modref@ref##1#1##2\egroup##3{%
\@ifempty{##2}{%
\expandafter\@setref\csname r@##1\endcsname{##3\expandafter\@iden}{##1}%
}{%
\modref@@ref##1#1##2\egroup##3}}%
% \end{macrocode}
% \end{macro}
% \begin{macro}{\modref@@ref}
% Having been given an alleged style prefix, and a suffix making up the remainder of the reference label, the command
% \makeatletter\cmd\modref@@ref\makeatother\ attempts to determine whether or not the prefix corresponds to a defined style.
% We do this by testing for the existence of the command sequence "\modref@"<label-prefix>, which will be the macro which is
% applied for that style.
% If that macro does not exist, we invoke \makeatletter\cmd\@setref\makeatother\ on the reference, using the global
% format specified in "##3" and the identity function as the ``style format''.
% Otherwise, we obtain the command sequence for the reference's style-format, and invoke \makeatletter\cmd\@setref\makeatother\
% using the global format in "##3" and that style-format.
% \begin{macrocode}
\def\modref@@ref##1#1##2#1\egroup##3{%
\@ifundefined{@modref@##1}{%
\expandafter\@setref\csname r@##1#1##2\endcsname{%
##3\expandafter\@iden}{##1#1##2}%
}{%
\expandafter\def\expandafter\@tempa\expandafter{%
\csname @modref@##1\endcsname}%
\expandafter\@setref\csname r@##1#1##2\endcsname{%
##3\expandafter\@tempa}{##1#1##2}%
}}%
% \end{macrocode}
% \end{macro}
%
% This completes the definition of \cmd\setrefdelimiter: it only remains to execute it for the delimiter which has been chosen.
% This causes \cmd\ref\ to be redefined using the code above, using whatever string is contained in \makeatletter\cmd\modref@delimiter
% \makeatother\ in the syntax of the definitions.
% However, if the "delimiter" option was used, and set to the empty string for some reason, we produce an error.
% \begin{macrocode}
}%
\ifx\modref@delimiter\@empty
\modref@error{Option "delimiter" must be set to a non-empty value}{%
The option "delimiter" was used, but seems to have been set to the
empty string. I require a character, or a multi-character string, to
delimit reference style names within cross-reference labels. If in
doubt, just remove the "delimiter" option, and this should fix things.}%
\else
\expandafter\setrefdelimiter\expandafter{\modref@delimiter}%
\fi
% \end{macrocode}
% \end{macro}
%
% \subsection{Defining global reference formats and special reference styles}
%
% \begin{macro}{\GlobalRefStyle}
% \begin{macro}{\GlobalVarRefStyle}
% We provide two commands for modifying the global format for \cmd\ref\ and \cmd\varref, each of which accept an argument describing
% a two-argument macro.
% They each create such a macro: these will be used to redefine \makeatletter\cmd\modref@basestyle\makeatother\ or
% \makeatletter\cmd\modref@varbasestyle\makeatother.
% \begin{macrocode}
\newcommand\GlobalRefStyle[1]{\def\modref@@basestyle##1##2{#1}}
\newcommand\GlobalVarRefStyle[1]{\def\modref@@varbasestyle##1##2{#1}}
\@onlypreamble\GlobalRefStyle
\@onlypreamble\GlobalVarRefStyle
% \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\modref@basestyle}
% \begin{macro}{\modref@varbasestyle}
% We have already met \makeatletter\cmd\modref@basestyle\makeatother\ and \makeatletter\cmd\modref@varbasestyle\makeatother,
% which were used by \cmd\ref\ and \cmd\varref\ respectively; these commands are used to store the user-customizable ``global style''
% that gets applied to all references, whether or not they have a defined style type.
% They both take three arguments: a macro to apply as a style type, and two more corresponding to the cross-reference value
% and the page number of the reference.
% They are designed in such a way that using the argument
% \begin{center}
% "{\modref@basestyle\expandafter\@modref@"<style-name>"}"
% \end{center}
% in place of \makeatletter\cmd\@firstoftwo\makeatother\ in a call to \makeatletter\cmd\@setref\makeatother, as in the original
% definition of \cmd\ref\ in "latex.ltx", will have the effect of applying \makeatletter\cmd\modref@basestyle\makeatother\ to
% precisely the specified style-format, and the cross-reference and page number.
% It is easy to verify that this is exactly what is done in \makeatletter\cmd\modref@@ref\makeatother\ when called by the new
% implementation of \cmd\ref; similar statements hold for \cmd\varref.
%
% We set \makeatletter\cmd\modref@basestyle\makeatother\ to apply the any format defined by \cmd\GlobalRefStyle, with the
% styled reference as the first argument, and the page number as the second; and similarly for \makeatletter\cmd
% \modref@varbasestyle\makeatother.
% We then define the global reference format in each case to the identity function.
% In the case where the style-format is replaced by the \makeatletter\cmd\@iden\makeatother\ macro, the effect of the
% reference formatting then reduces the usage above to the traditional meaning of \cmd\ref, defined in terms of passing
% the macro \makeatletter\cmd\@firstoftwo\makeatother\ to \makeatletter\cmd\@setref\makeatother.
% \begin{macrocode}
\def\modref@basestyle#1#2#3{\modref@@basestyle{#1{#2}}{#3}}%
\def\modref@varbasestyle#1#2#3{\modref@@varbasestyle{#1{#2}}{#3}}%
\GlobalRefStyle{#1}%
\GlobalVarRefStyle{#1}%
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\refstyle}
% The \cmd\refstyle\ macro for defining particular reference styles takes a style-name <style-name> as its first argument, and
% the formatting of the style as the second argument; the latter may use at most one argument, for the reference label.
% The command \cmd\refstyle\ defines a command sequence \makeatletter\cmd\@modref@\makeatother<style-name> which takes one argument
% and applies the required formatting.
% In order to allow easy overriding of reference styles (\eg\ in order to redefine the formatting of \cmd\eqref\ when using the
% "eqref" option), we do not require that reference style names be unique.
% We require \cmd\refstyle\ to only be used in the document pre-amble; and if \cmd\refstyle\ is already defined, we produce an error.
% \begin{macrocode}
\edef\reserved@a{refstyle}%
\@ifundefined\reserved@a{%
\newcommand\refstyle[2]{%
\expandafter\def\csname @modref@#1\endcsname##1{#2}}%
}{%
\modref@error{%
Command \string\refstyle\ defined already; refer to the help message.
}{%
The "modref" package defines the command \string\refstyle; however,
in this instance, \string\refstyle\ already had a meaning when "modref"
started running. Please determine what is defining \string\refstyle, and
whether you need it.}}
% \end{macrocode}
% \end{macro}
%
% \subsection{Customizing \cmd\eqref\ and displayed equation tags}
%
% \begin{macro}{\eqrefstyle}
% \begin{macro}{\modref@trivbasestyle}
% Changes to the style of \cmd\eqref\ can be made, independently of changes to the displayed equation tags, by redefining
% \cmd\eqref\ to call the macro \makeatletter\cmd\modref@eqref\makeatother, and redefining that macro accordingly.
% The way in which \cmd\eqref\ invokes \makeatletter\cmd\modref@eqref\makeatother\ is to use it as part of an argument to
% \makeatletter\cmd\@setref\makeatother\ in such a way as to apply the style before resolving the reference (so that undefined
% references will result in the output ``\ref{undef-reference}'' rather than a transformation of it).
% However, we only redefine \cmd\eqref\ if \cmd\eqrefstyle\ is called, so that it retains the meaning given to it by "amsmath"
% unless it is explicitly redefined.
% We also define a ``trivial'' base style, \emph{\`a la} \makeatletter\cmd\modref@basestyle\makeatother, to facilitate this.
% \begin{macrocode}
\newcommand\eqrefstyle[1]{%
\def\eqref##1{%
\maketag@@@{%
\expandafter\@setref\csname r@##1\endcsname{%
\modref@trivbasestyle\expandafter\modref@eqref}{##1}}}%
\def\modref@eqref##1{#1}}%
\def\modref@trivbasestyle#1#2#3{#1{#2}}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\displaytagstyle}
% To set the style of tags in displayed equations, we redefine the internal macro \makeatletter\cmd\tagform@\makeatother\ from
% "amsmath.sty" to apply the style that we want, which will be defined by a macro \makeatletter\cmd\modref@tagstyle\makeatother.
% \begin{macrocode}
\newcommand\displaytagstyle[1]{%
\def\modref@tagstyle##1{#1}%
\def\tagform@##1{\maketag@@@{\modref@tagstyle{##1}}}%
% \end{macrocode}
% Because \cmd\eqref\ also uses the command \makeatletter\cmd\tagform@\makeatother\ for its implementation, a call to
% \cmd\displayTagStyle\ also re-implements \cmd\eqref\ using \cmd\eqrefstyle\ --- but only if \cmd\eqref\ hasn't already
% been re-implemented.
% Whether or not it has is determined by testing if \makeatletter\cmd\modref@eqref\makeatother\ is well-defined.
% The style that it sets is the original meaning of \cmd\eqref\ as defined in "amsmath.sty", except for expanding the macros
% \makeatletter\cmd\tagform@\makeatother\ and \cmd\ref, and removing the macro \makeatletter\cmd\maketag@@@\makeatother\
% (which is already part of the new definition of \cmd\eqref).
% \begin{macrocode}
\@ifundefined{modref@eqref}{%
\eqrefstyle{\textup{(\ignorespaces#1\unskip\@@italiccorr)}}%
}\relax
}%
% \end{macrocode}
% \end{macro}
%
% \Finale
%
% \section{Feedback}
%
% I would appreciate any feedback on this package that anyone may have, including error reports,
% suggestions for modest extensions, and criticism (whether about the purpose or about the implementation
% of the package). Please send your feedback to "jdebeaud@math.uwaterloo.ca", with the phrase
% ``\ModRef\ package'' (or something very similar) in the subject line. Thanks!
\makeatother
\endinput