path: root/macros/latex/contrib/modref/modref.dtx

% \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