summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/modref
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/modref
Initial commit
Diffstat (limited to 'macros/latex/contrib/modref')
-rw-r--r--macros/latex/contrib/modref/README5
-rw-r--r--macros/latex/contrib/modref/modref.dtx909
-rw-r--r--macros/latex/contrib/modref/modref.ins30
-rw-r--r--macros/latex/contrib/modref/modref.pdfbin0 -> 166076 bytes
4 files changed, 944 insertions, 0 deletions
diff --git a/macros/latex/contrib/modref/README b/macros/latex/contrib/modref/README
new file mode 100644
index 0000000000..a2a63ab3ef
--- /dev/null
+++ b/macros/latex/contrib/modref/README
@@ -0,0 +1,5 @@
+The "modref" package contains macros which allow authors to
+easily customize how cross-references appear in their document,
+both in general (across all cross-references) and for particular
+types of references (identified by a prefix in the reference label),
+in a very generic manner. \ No newline at end of file
diff --git a/macros/latex/contrib/modref/modref.dtx b/macros/latex/contrib/modref/modref.dtx
new file mode 100644
index 0000000000..72550f452b
--- /dev/null
+++ b/macros/latex/contrib/modref/modref.dtx
@@ -0,0 +1,909 @@
+% \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
+
+
+
+
diff --git a/macros/latex/contrib/modref/modref.ins b/macros/latex/contrib/modref/modref.ins
new file mode 100644
index 0000000000..88050290a0
--- /dev/null
+++ b/macros/latex/contrib/modref/modref.ins
@@ -0,0 +1,30 @@
+%% `modref.ins'
+%%
+%% Docstrip installation instruction file for package `modref'
+%%
+%% J. Niel de Beaudrap <jdebeaud@math.uwaterloo.ca> (jrnb)
+%%
+%% February 3, 2009
+
+\def\batchfile{modref.ins}
+\def\filedate{2007.02.18}
+\input docstrip.tex
+\keepsilent
+\Msg{*** Generating the `modref' package ***}
+\askforoverwritefalse
+\generate{\file{modref.sty}{\from{modref.dtx}{package}}}
+\generate{\file{modref.drv}{\from{modref.dtx}{driver}}}
+%
+\ifToplevel{%
+\Msg{_____________________________________________________________}
+\Msg{}
+\Msg{ Thanks for building the "modref" package! Don't forget to}
+\Msg{ put modref.sty in a directory/folder searched by TeX.}
+\Msg{}
+\Msg{ To produce the documentation, run LaTeX on "modref.dtx".}
+\Msg{_____________________________________________________________}
+\Msg{}
+}
+\endinput
+%%
+%% End of file `modref.ins'
diff --git a/macros/latex/contrib/modref/modref.pdf b/macros/latex/contrib/modref/modref.pdf
new file mode 100644
index 0000000000..b79b52f9a7
--- /dev/null
+++ b/macros/latex/contrib/modref/modref.pdf
Binary files differ