| 1 |
% \iffalse meta-comment |
| 2 |
%% ============================================================================================= |
| 3 |
% |
| 4 |
% Copyright 2009 J. Niel de Beaudrap. |
| 5 |
% |
| 6 |
% This file may be distributed and/or modified under the |
| 7 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 8 |
% of this license or (at your option) any later version. |
| 9 |
% The latest version of this license is in |
| 10 |
% http://www.latex-project.org/lppl.txt |
| 11 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 12 |
% version 2005/12/01 or later. |
| 13 |
% |
| 14 |
% This file has the LPPL maintenance status "maintained". |
| 15 |
% |
| 16 |
% The list of all files belonging to the LaTeX base distribution is |
| 17 |
% given in the file `manifest.txt'. See also `legal.txt' for additional |
| 18 |
% information. |
| 19 |
% |
| 20 |
% The list of derived (unpacked) files belonging to the distribution |
| 21 |
% and covered by LPPL is defined by the unpacking scripts (with |
| 22 |
% extension .ins) which are part of the distribution. |
| 23 |
% |
| 24 |
% \fi |
| 25 |
% ^^A -*-LaTeX-*- |
| 26 |
% |
| 27 |
% ^^A These shouldn't come out in .ist files, hence the module |
| 28 |
% ^^A comments, or in the printed version, hence temporary comment |
| 29 |
% ^^A category for `<' |
| 30 |
%\catcode`\<=14 |
| 31 |
%<+package>\def\basename{modref} |
| 32 |
%<+package>\def\fullname{restyle: cross-referencing hacks for LaTeX} |
| 33 |
%<+package>\def\revisiondate{2009/02/02} |
| 34 |
%<+package>\def\revision{0.9} |
| 35 |
%<+package>\def\writtenby{J. Niel de Beaudrap} |
| 36 |
%\catcode`\<=12 |
| 37 |
% |
| 38 |
% \CheckSum{0} |
| 39 |
%% \CharacterTable |
| 40 |
%% {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 |
| 41 |
%% 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 |
| 42 |
%% Digits \0\1\2\3\4\5\6\7\8\9 |
| 43 |
%% Exclamation \! Double quote \" Hash (number) \# |
| 44 |
%% Dollar \$ Percent \% Ampersand \& |
| 45 |
%% Acute accent \' Left paren \( Right paren \) |
| 46 |
%% Asterisk \* Plus \+ Comma \, |
| 47 |
%% Minus \- Point \. Solidus \/ |
| 48 |
%% Colon \: Semicolon \; Less than \< |
| 49 |
%% Equals \= Greater than \> Question mark \? |
| 50 |
%% Commercial at \@ Left bracket \[ Backslash \\ |
| 51 |
%% Right bracket \] Circumflex \^ Underscore \_ |
| 52 |
%% Grave accent \` Left brace \{ Vertical bar \| |
| 53 |
%% Right brace \} Tilde \~} |
| 54 |
%% |
| 55 |
%\iffalse This is a METACOMMENT |
| 56 |
% Everything up to the next `\ fi' (without a blank) will |
| 57 |
% be ignored. This is necessary because `%' may no longer |
| 58 |
% be a comment mark when this file is read in. |
| 59 |
% |
| 60 |
%% Package `modref' to use with LaTeX 2e |
| 61 |
%% Copyright (C) 2007 J. Niel de Beaudrap, all rights reserved. |
| 62 |
% |
| 63 |
% |
| 64 |
% Version: Date: Changes: |
| 65 |
% |
| 66 |
% 1.0 First revision. |
| 67 |
% |
| 68 |
% \changes{v1.0}{2007/12/16}{First revision.} |
| 69 |
%\fi |
| 70 |
% |
| 71 |
% \setcounter{StandardModuleDepth}{1} |
| 72 |
% |
| 73 |
% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print |
| 74 |
% \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign |
| 75 |
% |
| 76 |
% \newcommand\ModRef{\texttt{modref}} |
| 77 |
% |
| 78 |
% \GetFileInfo{modref.sty} |
| 79 |
% |
| 80 |
% \iffalse |
| 81 |
% ============================================================================================= |
| 82 |
% \fi |
| 83 |
%\catcode`\<=14 |
| 84 |
%<+package>\typeout{-------} |
| 85 |
%<+package>\typeout{\fullname \space v\revision \space(\basename)} |
| 86 |
%<+package>\typeout{\writtenby, \revisiondate} |
| 87 |
%<+package>\typeout{-------} |
| 88 |
%<+package>\ProvidesPackage{modref}[\revisiondate {} {v\revision} {\writtenby}] |
| 89 |
%<+package>\RequirePackage{kvoptions} |
| 90 |
%<+package> |
| 91 |
%<+package>\DeclareOption*{\PackageWarning{Unknown option `\CurrentOption'.}} |
| 92 |
%<+package>\makeatletter |
| 93 |
%\catcode`\<=12 |
| 94 |
% \iffalse |
| 95 |
% ============================================================================================= |
| 96 |
% \fi |
| 97 |
%\iffalse |
| 98 |
%<*driver> |
| 99 |
\documentclass[draft]{ltxdoc} |
| 100 |
\usepackage[left=4.5cm,right=3cm,top=3cm,bottom=3cm]{geometry} |
| 101 |
\usepackage{amsmath,amsthm} |
| 102 |
\usepackage{modref} |
| 103 |
% \EnableCrossrefs |
| 104 |
% \DisableCrossrefs % Say \DisableCrossrefs if index is ready |
| 105 |
% \CodelineIndex |
| 106 |
% \RecordChanges % Gather update information |
| 107 |
% \OnlyDescription % comment out for implementation details |
| 108 |
% \OldMakeindex % use if your MakeIndex is pre-v2.9 |
| 109 |
\setlength\hfuzz{15pt} % dont make so many |
| 110 |
\hbadness=7000 % over and under full box warnings |
| 111 |
|
| 112 |
\refstyle{itemNo}{[Item~\##1]} |
| 113 |
\refstyle{numero}{\texttt{\itshape numero~#1}} |
| 114 |
\refstyle{def}{Definition~#1} |
| 115 |
\refstyle{lemma}{Lemma~#1} |
| 116 |
\refstyle{thm}{Theorem~#1} |
| 117 |
\refstyle{fig}{Figure~#1} |
| 118 |
\refstyle{eqn}{Eqn.~#1} |
| 119 |
\eqrefstyle{\textbf{(#1)}} |
| 120 |
\displaytagstyle{{\Large$\bigcirc\mspace{-12mu}$}#1} |
| 121 |
\stepcounter{equation} |
| 122 |
|
| 123 |
\makeatletter |
| 124 |
\newenvironment{headerlist}{% |
| 125 |
\setlength\topsep{\baselineskip}% |
| 126 |
\setlength\parsep{1.3em}% |
| 127 |
\setlength\parskip{1.3em}% |
| 128 |
\setlength\listparindent{0ex}% |
| 129 |
\def\next@item[##1]{% |
| 130 |
\def\item{\egroup\next@item} |
| 131 |
\@inmatherr\item |
| 132 |
\bgroup |
| 133 |
\addtolength\leftskip{2.5em}% |
| 134 |
\par\noindent\hspace{-2.5em}\mbox{\headerliststyle{##1}}~\\[1ex]% |
| 135 |
\setlength\parindent{0ex}% |
| 136 |
\setlength\parskip{1ex}% |
| 137 |
\ignorespaces} |
| 138 |
\let\item\next@item |
| 139 |
}{% |
| 140 |
\par\egroup\leavevmode\noindent\ignorespaces |
| 141 |
} |
| 142 |
\newcommand\headerliststyle[1]{\texttt{\mdseries\upshape #1}} |
| 143 |
\makeatother |
| 144 |
|
| 145 |
\newcommand\ie{\textit{i.e.}} |
| 146 |
\newcommand\eg{\textit{e.g.}} |
| 147 |
\newcommand\etc{\textit{etc.}} |
| 148 |
|
| 149 |
\begin{document} |
| 150 |
\DocInput{modref.dtx} |
| 151 |
\end{document} |
| 152 |
%</driver> |
| 153 |
% \fi |
| 154 |
% |
| 155 |
% \DeleteShortVerb\| |
| 156 |
% \MakeShortVerb\" |
| 157 |
% |
| 158 |
% \makeatletter |
| 159 |
% \newenvironment{codeexample}[1][rm] |
| 160 |
% {\[ \mspace{10mu}\begin{minipage}{0.95\textwidth} \def\@tempa{#1} \begin{\@tempa}} |
| 161 |
% {\end{\@tempa} \end{minipage} \\[-1em] \]} |
| 162 |
% |
| 163 |
% \def\lt{<} |
| 164 |
% \catcode`\<=13 |
| 165 |
% \def\@less@char{<} |
| 166 |
% \expandafter\def\@less@char#1>{$\left\langle \textrm{\mdseries\itshape #1} \right\rangle$} |
| 167 |
% \makeatother |
| 168 |
% \newcommand\descr[1]{<\textit{#1}>} |
| 169 |
% \newcommand\op[1]{\mathrm{#1}} ^^A %\mathop{\operator@font #1}} |
| 170 |
% |
| 171 |
% \newcommand\DescribeOption[1]{\DescribeMacro{option:\;#1}} |
| 172 |
% \newenvironment{option}[1]{\begin{environment}{option:\;#1}}{\end{environment}} |
| 173 |
% |
| 174 |
% |
| 175 |
% \iffalse |
| 176 |
% ============================================================================================= |
| 177 |
% \fi |
| 178 |
% |
| 179 |
% \title{The \ModRef\ Package\thanks |
| 180 |
% {This file has version number \fileversion{} dated \filedate{}.}} |
| 181 |
% \author{Niel de Beaudrap} |
| 182 |
% |
| 183 |
% \maketitle |
| 184 |
% |
| 185 |
% \begin{abstract} |
| 186 |
% This package defines some hacks to allow authors to define customized output |
| 187 |
% for cross-references of different types, based on the reference label. |
| 188 |
% \end{abstract} |
| 189 |
% |
| 190 |
% \section{The purpose and overview of \ModRef} |
| 191 |
% |
| 192 |
% Usually, when labelling equations, definitions, figures, \etc\ in a document, experienced authors will give their |
| 193 |
% labels intelligent names indicating the kind of reference, such as "eqn:quadratic", "def-integral", "fig.instrument-layout", |
| 194 |
% or similar labels. |
| 195 |
% In the course of using cross-references, the author will then proceed to repeatedly write same text to accompany each instance |
| 196 |
% of these labels throughout their document, as in the following examples: |
| 197 |
% \begin{verbatim} |
| 198 |
% Theorem~\ref{thm:fundmental-calculus} |
| 199 |
% Theorem~\ref{thm:intermediate-value} |
| 200 |
% Theorem~\ref{thm:four-colour} |
| 201 |
% |
| 202 |
% Definition~\ref{def:hilbert-space} |
| 203 |
% Definition~\ref{def:delta-dirac} |
| 204 |
% |
| 205 |
% Figure~\ref{fig:instrument-layout} |
| 206 |
% Figure~\ref{fig:experimental-data} |
| 207 |
% Figure~\ref{fig:nine-hundred-billion} |
| 208 |
% Figure~\ref{fig:newton} |
| 209 |
% \end{verbatim} |
| 210 |
% \vspace{-\baselineskip} |
| 211 |
% and so on. |
| 212 |
% Given that the references are retrieved from the values of counters written to the auxiliary file, one solution might be to |
| 213 |
% redefine the relevant counters, \eg\ as in |
| 214 |
% \begin{verbatim} |
| 215 |
% \renewcommand\thetheorem{Theorem~\arabic{theorem}} |
| 216 |
% \end{verbatim} |
| 217 |
% \vspace{-\baselineskip} |
| 218 |
% but it is occasionally still desirable to retrieve the reference without the title, as when referring to multiple similar references, |
| 219 |
% such as |
| 220 |
% \begin{verbatim} |
| 221 |
% Theorems~\ref{thm:foo} and~\ref{thm:bar} |
| 222 |
% \end{verbatim} |
| 223 |
% \vspace{-\baselineskip} |
| 224 |
% so that a simple strategy of redefining "\thetheorem" is inadequate. |
| 225 |
% More sophisticated approaches involving redefining how counters are written to the auxiliary file will also produce problems, \eg |
| 226 |
% when one counter ``counts within'' another: for instance, if theorem numbers are of the format "\thechapter-\arabic{theorem}", the |
| 227 |
% theorem label would also inherit the labelling of the chapter reference (which is unproductive). |
| 228 |
% |
| 229 |
% However, if the document author names reference labels in a literate manner, it is possible to automate the production |
| 230 |
% of the accompanying text by scanning those reference labels, in a way totally independent of how the counter is defined, and |
| 231 |
% in a way which does not affect how the reference is recorded in the auxiliary file. |
| 232 |
% It is only necessary to allow the formatting to vary somehow depending on the label. |
| 233 |
% However, as not everyone uses the same labelling scheme for their cross-references, the way in which reference-labels map |
| 234 |
% to reference-formatting should be fairly flexible. |
| 235 |
% |
| 236 |
% The \ModRef\ package provides the functionality to easily define customized output for the \cmd\ref\ command by |
| 237 |
% identifying what sort of cross-reference is being made, based on an initial string of characters in the reference label. |
| 238 |
% This functionality is provided in a transparent manner, in that only changes the output of \cmd\ref\ for those cases |
| 239 |
% defined by the user, and the way in which those references are formatted is also specified by the user. |
| 240 |
% It also provides a way for authors to perform more powerful tasks, such as having every reference produce a margin note |
| 241 |
% in a completely customizable fashion, and easy customization of the appearance of displayed equation numbers in "amsmath" |
| 242 |
% environments. |
| 243 |
% |
| 244 |
% \subsection{Comparison with \texttt{fancyref}} |
| 245 |
% |
| 246 |
% Similar functionality to what \ModRef\ provides has been available since 1999 in the "fancyref" package.\footnote{^^A |
| 247 |
% The core functionality of \ModRef\ was developped independently of "fancyref": my sense of whether someone would have done |
| 248 |
% the same task before failed me in this instance, and I discovered the package after having implemented the commands |
| 249 |
% \cmd\refstyle, \cmd\setrefdelimiter, and an earlier version of \cmd\eqrefstyle\ (not to mention most of this document). |
| 250 |
% However, much of the functionality of this package as it exists currently was prompted by ideas derived from "fancyref".} |
| 251 |
% The functionality provided by \ModRef\ differs from that of "fancyref" in the following ways: |
| 252 |
% \begin{itemize} |
| 253 |
% \item |
| 254 |
% The syntax for defining new reference styles is simpler: \ModRef\ does not require the author provide a macro in which |
| 255 |
% to store each new reference style. |
| 256 |
% |
| 257 |
% \item |
| 258 |
% Authors can also use \ModRef\ to define top-level reference customization which is applied to all well-formed |
| 259 |
% references in a \emph{general} way, using the customized cross-references and the page-number of the reference as arguments, |
| 260 |
% using similar syntax to defining any other macro. |
| 261 |
% (The "fancyref" package enables putting all references in parentheses, putting references in margin-notes, and including |
| 262 |
% page-numbers \emph{\`a la} "varioref" in all references; the documentation also advertises customizable hooks.) |
| 263 |
% |
| 264 |
% \item |
| 265 |
% The behaviour of \cmd\ref\ is changed to use the customized reference behaviour. |
| 266 |
% (Purists who find this distasteful but who still with to use \ModRef\ --- or any user who just wishes to access the |
| 267 |
% original functionality of \cmd\ref\ --- can find the original behaviour retained in the macro \cmd\Ref.) |
| 268 |
% |
| 269 |
% \item |
| 270 |
% The \ModRef\ package also enables the customization of displayed equation tags, and of the output of the command \cmd\eqref, |
| 271 |
% as defined by the "amsmath" package. |
| 272 |
% \end{itemize} |
| 273 |
% However, the main distinction between \ModRef\ and "fancyref" is in the design philosophy: |
| 274 |
% \begin{itemize} |
| 275 |
% \item[---] |
| 276 |
% "fancyref" appears to have been written in an attempt to anticipate anything that an author might wish to do: therefore, it |
| 277 |
% has a great many redundant pre-defined macros, which one may change to achieve varying degrees of change from the default |
| 278 |
% configuration; |
| 279 |
% |
| 280 |
% \item[---] |
| 281 |
% \ModRef\ was written to have a simple interface for customizing references, without many assumptions about how an author |
| 282 |
% might wish to customize their references (except that it be not too tedious): any changes defined by an author are relative to |
| 283 |
% the default behaviour of \LaTeX. |
| 284 |
% \end{itemize} |
| 285 |
% 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 |
| 286 |
% customize how cross-references appear in their documents. |
| 287 |
% |
| 288 |
% \subsection{Functionality provided by \ModRef} |
| 289 |
% |
| 290 |
% The \ModRef\ package introduces the following concepts, and access to control how these concepts are applied to |
| 291 |
% cross-references in documents. |
| 292 |
% \begin{headerlist} |
| 293 |
% \renewcommand\headerliststyle[1]{\textrm{\mdseries\itshape #1}} |
| 294 |
% |
| 295 |
% \item[Special reference styles] |
| 296 |
% A ``special'' reference style is a command which is performed on references of a certain type. |
| 297 |
% What command is performed depends on the type of the reference; and the type of any reference is determined from its label. |
| 298 |
% |
| 299 |
% The author defines one or more styles by specifying a ``prefix'' or ``style name'' for each style --- such as ``"dfn"'' for |
| 300 |
% definitions, ``"eq"'' for equations, \etc\ --- and describes the formatting to be applied for that reference type. |
| 301 |
% For each reference, \ModRef\ then attempts to determine the type of the reference by matching the label against known |
| 302 |
% style names. |
| 303 |
% The name is delimited by default using a colon (``":"'') character (but the delimiter may be chosen by the author, and |
| 304 |
% even changed mid-document): thus, an equation reference might have a label such as ``"eq:quadratic"'', a definition might have |
| 305 |
% a label ``"dfn:vectorSpace"'', and so on. |
| 306 |
% |
| 307 |
% The result of applying a reference style to a particular type of reference is a \emph{customized reference}. |
| 308 |
% Any reference whose label does not contain a defined reference type has no special style applied to it. |
| 309 |
% |
| 310 |
% The command to use to define special reference styles is \cmd\refstyle; the command to change the delimiter mid-document is |
| 311 |
% \cmd\setrefdelimiter. |
| 312 |
% (There is also a package option "delimiter" which allows the delimiter to be set at the beginning of the document.) |
| 313 |
% |
| 314 |
% \item[Global reference styles] |
| 315 |
% A ``global'' reference style is a command which is performed at \emph{every} reference. |
| 316 |
% Only two global reference styles may be defined for a given document: a default one and a ``variant'' one. |
| 317 |
% The inputs to a global reference style are the customized reference (if the reference is of a particular type) and the page number; |
| 318 |
% authors are free to use these arguments however they wish to define the behaviour of the \cmd\ref\ function. |
| 319 |
% Initially, the behaviour is just to pass on the (possibly customized) reference unchanged, omitting the page number. |
| 320 |
% |
| 321 |
% The commands to define the global reference styles are \cmd\GlobalRefStyle\ and \cmd\GlobalVarRefStyle; the commands |
| 322 |
% which apply the two different reference styles are \cmd\ref\ and \cmd\varref. |
| 323 |
% |
| 324 |
% \item[Equation references and displayed equation tags] |
| 325 |
% There is exactly one exception to the above description of how references are customized: if the author uses the "amsmath" |
| 326 |
% package, the output of the command \cmd\eqref\ remains \emph{totally unmodified} --- unless, of course, they wish to modify it; |
| 327 |
% then \ModRef\ facilitates doing this. |
| 328 |
% |
| 329 |
% Because the output of \cmd\eqref\ is by design intended to be different from that of \cmd\ref, global reference styles |
| 330 |
% are never applied to any application of \cmd\eqref. |
| 331 |
% As well, \cmd\eqref\ is never defined to attempt to infer the type of a reference from its label (presumably, it's an equation). |
| 332 |
% However, \ModRef\ does allow different reference styles to be defined for \cmd\eqref. |
| 333 |
% |
| 334 |
% While we're customizing cross-references to equations, why not allow how the equations themselves are labelled to be customized? |
| 335 |
% This allows the author to fine-tune the appearance of equation tags. |
| 336 |
% However, these customizations do not affect the output of \cmd\eqref, or vice-versa. |
| 337 |
% |
| 338 |
% The command to redefine the behaviour of \cmd\eqref\ is \cmd\eqrefstyle; the command to redefine how equation numbers |
| 339 |
% appear in displayed equations is \cmd\displaytagstyle. |
| 340 |
% |
| 341 |
%^^A \item[Cross-references without styles] |
| 342 |
%^^A It is possible to access the original functionality of \cmd\ref\ in the macro \cmd\Ref. |
| 343 |
% \end{headerlist} |
| 344 |
% \hspace{-2\baselineskip} No special reference styles are pre-defined by \ModRef, and no global styles are defined (except |
| 345 |
% for the ``trivial'' styles described above); only the reference-styles which the document author defines will be applied. |
| 346 |
% |
| 347 |
% \subsection{Package options} |
| 348 |
% |
| 349 |
% This version of \ModRef\ has the following option: |
| 350 |
% |
| 351 |
% \begin{headerlist} |
| 352 |
% \item[delimiter=<string>] |
| 353 |
% This option controls the string which delimits the prefix defining the type of a particular reference. |
| 354 |
% If omitted, the default value is a single colon character (``":"''). |
| 355 |
% This string may be set to any value, except \textbf{(a)}~the empty string, \textbf{(b)}~any string containing a comma, |
| 356 |
% or \textbf{(c)}~any string containing characters not allowed in package options by \LaTeX\ (\eg\ ``"{"'', ``"}"'', \etc) |
| 357 |
% \end{headerlist} |
| 358 |
% \vspace{-2\baselineskip} |
| 359 |
% |
| 360 |
% \subsection{Package dependencies/conflicts} |
| 361 |
% |
| 362 |
% The package \ModRef\ depends on the "kvoptions" package, which should be included in modern \LaTeXe\ distributions. |
| 363 |
% It is currently incompatible with the "hyperref" package: compatibility is planned for the next version. |
| 364 |
% |
| 365 |
% \subsection{Bugs} |
| 366 |
% |
| 367 |
% There are no known bugs in \ModRef. |
| 368 |
% |
| 369 |
% \iffalse |
| 370 |
% ============================================================================================= |
| 371 |
% \fi |
| 372 |
% |
| 373 |
% \section{How to use \ModRef} |
| 374 |
% |
| 375 |
% The \ModRef\ package is very simple. |
| 376 |
% The user interface essentially consists of two commands: the invocation "\usepackage{modref}" itself (which currently |
| 377 |
% accepts three options), and the command \cmd\refstyle; a few other macros are provided to perform auxiliary functions. |
| 378 |
% We will describe these in the opposite order. |
| 379 |
% |
| 380 |
% \subsection{Defining reference styles} |
| 381 |
% \label{numero:definingModRefs} |
| 382 |
% |
| 383 |
% \subsubsection*{Special reference styles} |
| 384 |
% |
| 385 |
%^^A The \ModRef\ package functions by redefining the command \cmd\ref\ in such a way as to interpret the cross-reference labels |
| 386 |
%^^A provided to it. |
| 387 |
%^^A Depending on an initial prefix --- which we will variously call a ``label prefix'' or ``style name'' --- it will then apply |
| 388 |
%^^A an author-defined style if one has been defined for the particular type of reference. |
| 389 |
% |
| 390 |
% \DescribeMacro{\refstyle} |
| 391 |
% Special reference styles can be defined for different label-prefixes using the \cmd\refstyle\ macro, which has the syntax: |
| 392 |
% \begin{center} |
| 393 |
% "\refstyle{"\textit{style-name}"}{"\textit{style-format}"}" |
| 394 |
% \end{center} |
| 395 |
% which defines a style with the given style-name. |
| 396 |
% (The reason for the mixed- |
| 397 |
% 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 |
| 398 |
% argument. |
| 399 |
% The value of that single argument should be interpreted as the \emph{usual} output of the \cmd\ref\ command: \ie\ |
| 400 |
% style-formats are descriptions of transformations to perform on ``ordinary'' cross-references. |
| 401 |
% |
| 402 |
% The \cmd\refstyle\ command can be used multiple times for a single reference-style in order to override previous definitions |
| 403 |
% of the style-formats for that style; however, it is recommended only to use it in the pre-amble to avoid confusion. |
| 404 |
% |
| 405 |
% \paragraph{Use cases.} |
| 406 |
% The effects of using \cmd\refstyle\ can be demonstrated as follows. |
| 407 |
% \begin{enumerate} |
| 408 |
% \item |
| 409 |
% \label{firstitem} |
| 410 |
% Style-names are identified from cross-reference labels by looking for a label-prefix, separated from the rest of the label |
| 411 |
% by a delimiter such as a colon (":") character. |
| 412 |
% For any cross-reference label which does not have such a delimiter, such as "genericlabel", the usual behaviour of \cmd\ref\ |
| 413 |
% applies. |
| 414 |
% |
| 415 |
% \textbf{Example.} |
| 416 |
% This list item is labelled with the command "\label{firstitem}". |
| 417 |
% This label doesn't contain an identifiable label-prefix, so "\ref{firstitem}" produces the output \ref{firstitem}, as usual. |
| 418 |
% As well, this document doesn't have a cross-references labelled "undef-reference"; therefore, "\ref{undef-reference}" |
| 419 |
% produces the output \ref{undef-reference}, as usual. |
| 420 |
% |
| 421 |
% \item |
| 422 |
% \label{item:second} |
| 423 |
% If a cross-reference label has an identifiable prefix, but this prefix does not correspond to a defined style-format, the |
| 424 |
% usual behaviour of \cmd\ref\ applies as well. |
| 425 |
% |
| 426 |
% \textbf{Example.} |
| 427 |
% This second list item is labelled with the command "\label{item:second}". |
| 428 |
% However, this document didn't define any style-name called ``"item"''; therefore, "\ref{item:second}" produces the output |
| 429 |
% \ref{item:second}. |
| 430 |
% |
| 431 |
% \item |
| 432 |
% \label{itemNo:third} |
| 433 |
% If a cross-reference label has an identifiable prefix which does correspond to a style-format, the style-format is applied |
| 434 |
% to the cross-reference. |
| 435 |
% |
| 436 |
% \textbf{Example.} |
| 437 |
% In the header of this document, the following reference style was defined: |
| 438 |
% \begin{verbatim} |
| 439 |
% \refstyle{itemNo}{[Item~\##1]} |
| 440 |
% \end{verbatim} |
| 441 |
% The label for this list item was defined using "\label{itemNo:third}". |
| 442 |
% Because the usual meaning of "\ref{itemNo:third}" would be \Ref{itemNo:third}, the resulting output of "\ref{itemNo:third}" |
| 443 |
% is \ref{itemNo:third}. |
| 444 |
% |
| 445 |
% \item |
| 446 |
% \label{numero:fourth} |
| 447 |
% The style-formats do not correspond in any way to individual counters, but only to the labels given to the references. |
| 448 |
% Thus, references which use the same counter may be given different styles, if this is a meaningful thing to do, simply by |
| 449 |
% making the label prefixes different; and references with different counters may be given the same reference style. |
| 450 |
% |
| 451 |
% \textbf{Example.} |
| 452 |
% In the header of this document, the following reference style was defined: |
| 453 |
% \begin{verbatim} |
| 454 |
% \refstyle{numero}{\texttt{\itshape numero~#1}} |
| 455 |
% \end{verbatim} |
| 456 |
% The label for this list item was defined using "\label{numero:fourth}": this gives rise to a different format of reference |
| 457 |
% than the reference style ``"itemNo"'' --- in particular, "\ref{numero:fourth}" produces \ref{numero:fourth}. |
| 458 |
% At the same time, the cross-reference label for this section is defined by "\label{numero:definingModRefs}"\,: thus, |
| 459 |
% "\ref{numero:definingModRefs}" produces \ref{numero:definingModRefs}. |
| 460 |
% |
| 461 |
% \item |
| 462 |
% The new implementation for \cmd\ref\ applies styles only to well-defined cross-references: that is, it acts as though the |
| 463 |
% customized output is the entire cross-reference. |
| 464 |
% |
| 465 |
% \textbf{Example.} |
| 466 |
% This document doesn't have any cross-reference "itemNo:undef-reference"; therefore, despite the fact that this |
| 467 |
% label contains the style-prefix ``"itemNo"'', the reference "\ref{itemNo:undef-reference}" produces the output |
| 468 |
% \ref{itemNo:undef-reference}, as with any ill-defined reference. |
| 469 |
% \end{enumerate} |
| 470 |
% A more coherent illustration of how to use \cmd\refstyle, and how it affects cross-references, is illustrated in \ref{fig:example}. |
| 471 |
% |
| 472 |
% \DescribeMacro{\eqrefstyle} |
| 473 |
% The syntax of \cmd\eqrefstyle\ is similar: it takes a single argument, specifying the style for any cross-reference using \cmd\eqref. |
| 474 |
% Global reference styles are not applied to uses of \cmd\eqref; and as with \cmd\ref, \cmd\eqref\ produces the output |
| 475 |
% \eqref{undefined-reference} when applied to undefined references. |
| 476 |
% |
| 477 |
% |
| 478 |
% \begin{figure}[t] |
| 479 |
% \begin{center} |
| 480 |
% \begin{minipage}{0.4\textwidth} |
| 481 |
% \begin{verbatim} |
| 482 |
% \refstyle{def}{Definition~#1} |
| 483 |
% \refstyle{lemma}{Lemma~#1} |
| 484 |
% \refstyle{thm}{Theorem~#1} |
| 485 |
% \refstyle{eqn}{Eqn.~#1} |
| 486 |
% |
| 487 |
% \eqrefstyle{\textbf{#1]}} |
| 488 |
% \displaytagstyle{{\Large% |
| 489 |
% $\bigcirc\mspace{-12mu}$}#1} |
| 490 |
% |
| 491 |
% % Main text: |
| 492 |
% |
| 493 |
% \begin{definition} |
| 494 |
% \label{def:lorentz} ... |
| 495 |
% \end{definition} |
| 496 |
% |
| 497 |
% \begin{lemma} |
| 498 |
% \label{lemma:simultaneity} ... |
| 499 |
% \end{lemma} |
| 500 |
% |
| 501 |
% \begin{theorem} |
| 502 |
% \label{thm:einstein} ... |
| 503 |
% \begin{gather} |
| 504 |
% \label{eqn:einstein} |
| 505 |
% E = mc^2 |
| 506 |
% \end{gather} |
| 507 |
% ... |
| 508 |
% \end{theorem} |
| 509 |
% |
| 510 |
% \ref{thm:einstein} ... |
| 511 |
% \eqref{eqn:einstein} ... |
| 512 |
% |
| 513 |
% \ref{def:lorentz} and |
| 514 |
% \ref{lemma:simultaneity} ... |
| 515 |
% \ref{eqn:einstein} ... |
| 516 |
% \end{verbatim} |
| 517 |
% \end{minipage} |
| 518 |
% ~\vrule~~ |
| 519 |
% \begin{minipage}{0.44\textwidth} |
| 520 |
% \newtheorem{lemma}{Lemma} \setcounter{lemma}{10} |
| 521 |
% \newtheorem{theorem}{Theorem} \setcounter{theorem}{3} |
| 522 |
% |
| 523 |
% \theoremstyle{definition} |
| 524 |
% \newtheorem{definition}{Definition} |
| 525 |
% \setcounter{definition}{4} \renewcommand\thedefinition{\Roman{definition}} |
| 526 |
% |
| 527 |
% \begin{definition} |
| 528 |
% \label{def:lorentz} |
| 529 |
% A theory of physics is \emph{Lorentz invariant} if [\ldots] |
| 530 |
% \end{definition}~\\[-1ex] |
| 531 |
% |
| 532 |
% \begin{lemma} |
| 533 |
% \label{lemma:simultaneity} |
| 534 |
% For two distinct events $A$ and $B$, there exists a reference frame in which they are simultaneous if \textup{[\ldots]} |
| 535 |
% \end{lemma}~\\[-1ex] |
| 536 |
% |
| 537 |
% \begin{theorem} |
| 538 |
% \label{thm:einstein} |
| 539 |
% The equivalent mass $m$ which is associated with some amount of energy $E$ is determined by the equation |
| 540 |
% \begin{gather} |
| 541 |
% \label{eqn:einstein} E = mc^2 |
| 542 |
% \end{gather} |
| 543 |
% where $c$ is the speed of light. |
| 544 |
% \end{theorem}~\\[-1ex] |
| 545 |
% |
| 546 |
% \ref{thm:einstein} is actually a corollary of a more general theorem, which generalizes \eqref{eqn:einstein} by |
| 547 |
% adding a dependency on momentum.\\ |
| 548 |
% |
| 549 |
% \ref{def:lorentz} and \ref{lemma:simultaneity} are also important ideas forming part of the Special |
| 550 |
% Theory of Relativity; but \ref{eqn:einstein} is its most famous formula. |
| 551 |
% \end{minipage} |
| 552 |
% \end{center} |
| 553 |
% \caption{\label{fig:example}% |
| 554 |
% Illustration of (some of) the functionality of \ModRef\ package.} |
| 555 |
% \end{figure} |
| 556 |
% |
| 557 |
% \subsubsection*{Global reference styles} |
| 558 |
% |
| 559 |
% Two different global reference styles can be defined using the \cmd\GlobalRefStyle\ and \cmd\GlobalVarRefStyle\ macros, |
| 560 |
% which have the syntax: |
| 561 |
% \begin{center} |
| 562 |
% \begin{minipage}{16em}\raggedright |
| 563 |
% "\GlobalRefStyle{"\textit{style-format}"}" \\ |
| 564 |
% "\GlobalVarRefStyle{"\textit{style-format}"}" |
| 565 |
% \end{minipage} |
| 566 |
% \end{center} |
| 567 |
% Again, the style-format is a macro definition, in this case using at most \emph{two} arguments. |
| 568 |
% The operands of these two arguments are the (customized) cross-reference, and the page number of that reference: thus, |
| 569 |
% the effect of a global reference style on a cross-reference might look something like |
| 570 |
% \begin{center} |
| 571 |
% \itshape"\GlobalStyleMacro"\upshape"{Definition~V}{13}" |
| 572 |
% \end{center} |
| 573 |
% for a definition on page thirteen, if definitions have been given a special reference style which inserts ``\,"Definition~"\,'' |
| 574 |
% at the beginning of every reference.\footnote{^^A |
| 575 |
% No macro specifically named \textit{\cmd\GlobalStyleMacro} is defined by \ModRef; this example is only intended for |
| 576 |
% illustrative purposes.} |
| 577 |
% |
| 578 |
% \DescribeMacro{\varref} |
| 579 |
% The global style defined by \cmd\GlobalRefStyle\ is applied to every cross-reference made with \cmd\ref; the variant global |
| 580 |
% style is applied for cross-references made with \cmd\varref. |
| 581 |
% (This is the only difference between \cmd\ref\ and \cmd\varref: the functionality will be otherwise identical.) |
| 582 |
% |
| 583 |
% Initially, both of the global reference styles do nothing except discard the page number, similarly to how \cmd\ref\ usually works. |
| 584 |
% In a typical application, it would be quite reasonable to leave the ``main'' global reference style unchanged, only to customize |
| 585 |
% the ``variant'' style. |
| 586 |
% For instance, one might sensibly choose to declare |
| 587 |
% \begin{verbatim} |
| 588 |
% \GlobalVarRefStyle{#1 (on page #2)} |
| 589 |
% \end{verbatim}\vspace{-\baselineskip} |
| 590 |
% to facilitate combining cross-referencing with page numbers, or |
| 591 |
% \begin{verbatim} |
| 592 |
% \GlobalVarRefStyle{(#1)} |
| 593 |
% \end{verbatim}\vspace{-\baselineskip} |
| 594 |
% to make it easy to turn a cross-reference into a parenthetical remark, in both cases by using \cmd\varref\ to perform the |
| 595 |
% cross-reference. |
| 596 |
% |
| 597 |
% To avoid too much non-uniformity in the appearance of cross-references, neither \cmd\GlobalRefStyle\ nor \cmd\GlobalVarRefStyle\ |
| 598 |
% are allowed outside of the document pre-amble. |
| 599 |
% |
| 600 |
% \subsection{Other features} |
| 601 |
% |
| 602 |
% \subsubsection*{Customizing the delimiter for reference types} |
| 603 |
% |
| 604 |
% \DescribeMacro{\setrefdelimiter} |
| 605 |
% In the examples above, the style-name was determined from cross-reference labels by scanning for the shortest substring at |
| 606 |
% the beginning of the label which did not contain a ``\:\!":"\:\!'' character. |
| 607 |
% However, authors can change this delimiter to any (non-empty) sequence of characters. |
| 608 |
% This can be done at the beginning of the document by invoking the package as |
| 609 |
% \begin{center} |
| 610 |
% "\usepackage[delimiter="<string>"]{modref}" |
| 611 |
% \end{center} |
| 612 |
% or mid-document by using the command "\setrefdelimiter{"\textit{string}"}"; all subsequent uses of \cmd\ref\ or \cmd\varref\ |
| 613 |
% will attempt to discover reference types using the new delimiter.\footnote{^^A |
| 614 |
% An immediate consequence of this is that references which previously had a defined ``reference type'' using the old delimiter |
| 615 |
% may not have a defined type using the new delimiter. |
| 616 |
% This will then have the effect of temporarily rescinding all special reference styles for those references using the old delimiter; |
| 617 |
% the styles can be restored by restoring that delimiter.} |
| 618 |
% |
| 619 |
% \subsubsection*{Customizing tags in \texttt{amsmath}-style displayed equations} |
| 620 |
% |
| 621 |
% \DescribeMacro{\displaytagstyle} |
| 622 |
% The style in which equation numbers are shown in the displayed-math environments defined by the "amsmath" package can be customized |
| 623 |
% using the \cmd\displaytagstyle\ command, which again has similar syntax to \cmd\refstyle\ and \cmd\eqref: |
| 624 |
% \begin{center} |
| 625 |
% "\displaytagstyle{"\textit{style-format}"}" |
| 626 |
% \end{center} |
| 627 |
% This also has the more general effect of defining the style for the \cmd\tag\ command, which can be used to insert |
| 628 |
% \emph{ad-hoc} equation tags in displayed math environments; the effect of the "\tag*" macro, however, is unaffected. |
| 629 |
% |
| 630 |
% \subsubsection*{Accessing the original functionality of \cmd\ref} |
| 631 |
% |
| 632 |
% \DescribeMacro{\Ref} |
| 633 |
% Sometimes it is useful to access a cross-reference without any special formatting. |
| 634 |
% To do this, one may use the \cmd\Ref\ command: this preserves the standard \LaTeXe\ functionality of \cmd\ref. |
| 635 |
% |
| 636 |
%^^A \paragraph{Example.} |
| 637 |
%^^A Although both items~\Ref{itemNo:third} and~\Ref{numero:fourth} in Section~\Ref{numero:definingModRefs} --- and the |
| 638 |
%^^A label for Section~\Ref{numero:definingModRefs} itself --- specify styles in their cross-reference labels (``"itemNo:third"'', |
| 639 |
%^^A ``"numero:fourth"'', and ``"numero:definingModRefs"'' respectively), we can refer to them without the special reference styles |
| 640 |
%^^A (as we did just above) by using the syntax "\Ref{itemNo:third}", "\Ref{numero:fourth}", and "\Ref{numero:definingModRefs}". |
| 641 |
% |
| 642 |
% |
| 643 |
% \iffalse |
| 644 |
% ========================================================================================== |
| 645 |
% \fi |
| 646 |
% |
| 647 |
% \section{Implementation} |
| 648 |
% |
| 649 |
% \subsection{Preliminary definitions} |
| 650 |
% |
| 651 |
% \begin{macro}{\modref@error} |
| 652 |
% First, we define a generic command "\modref@error" for producing errors. |
| 653 |
% \begin{macrocode} |
| 654 |
\newcommand\modref@error{\PackageError{modref}} |
| 655 |
% \end{macrocode} |
| 656 |
% \end{macro} |
| 657 |
% |
| 658 |
% \begin{macro}{\Ref} |
| 659 |
% As most of the subsequent definitions revolve around redefining aspects of the \cmd\ref\ command and friends, |
| 660 |
% we define the command \cmd\Ref\ which preserves the original behaviour for reference. |
| 661 |
% (If the macro \cmd\Ref\ is already defined, we produce an error.) |
| 662 |
% \begin{macrocode} |
| 663 |
\edef\reserved@a{Ref}% |
| 664 |
\@ifundefined\reserved@a{% |
| 665 |
\let\Ref\ref |
| 666 |
}{% |
| 667 |
\modref@error{% |
| 668 |
Command \string\Ref\ defined already; refer to the help message.% |
| 669 |
}{% |
| 670 |
The "modref" package defines the command \string\Ref\ to allow you (and |
| 671 |
the package) to use the original functionality of \string\ref. However, in |
| 672 |
this instance, \string\Ref\ already had a meaning when "modref" started |
| 673 |
running. Please determine what is defining \string\Ref, and whether you need |
| 674 |
it.}} |
| 675 |
% \end{macrocode} |
| 676 |
% \end{macro} |
| 677 |
% |
| 678 |
% \begin{macro}{\@ifempty} |
| 679 |
% \begin{macro}{\@xifempty} |
| 680 |
% We also crib the code for "\@ifempty" from "amsgen.sty" for simplicity. |
| 681 |
% \begin{macrocode} |
| 682 |
\def\@ifempty#1{\@xifempty#1@@..\@nil} |
| 683 |
\long\def\@xifempty#1#2@#3#4#5\@nil{ % |
| 684 |
\ifx#3#4\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi} |
| 685 |
% \end{macrocode} |
| 686 |
% \end{macro} |
| 687 |
% \end{macro} |
| 688 |
% |
| 689 |
% \subsection{Declaration and processing of the package options} |
| 690 |
% |
| 691 |
% Using the "kvoptions" package, we define the options for \ModRef, and the default value for the "fixtagsize" option. |
| 692 |
% \begin{macrocode} |
| 693 |
\DeclareStringOption[:]{delimiter} |
| 694 |
\ProcessKeyvalOptions* |
| 695 |
% \end{macrocode} |
| 696 |
% |
| 697 |
% \subsection{The core functionality, and customization of label delimiters} |
| 698 |
% |
| 699 |
% \begin{macro}{\setrefselimiter} |
| 700 |
% The macro \cmd\setrefdelimiter\ is a meta-macro which takes a single argument: this argument will be used as a delimiter |
| 701 |
% in further macros which define the infrastructure of \ModRef. |
| 702 |
% \begin{macrocode} |
| 703 |
\newcommand\setrefdelimiter[1]{% |
| 704 |
% \end{macrocode} |
| 705 |
% Throughout the following, "#1" denotes the delimiter to be used for identifying the style prefix in a cross-reference label. |
| 706 |
% \begin{macro}{\ref} |
| 707 |
% \begin{macro}{\varref} |
| 708 |
% The replacement for \cmd\ref\ will pass its argument onto another macro \makeatletter\cmd\modref@ref\makeatother, which will |
| 709 |
% attempt to parse the argument for a delimiter; we define \cmd\varref\ similarly. |
| 710 |
% They each pass a macro (\makeatletter\cmd\modref@basestyle\makeatother\ and \makeatletter\cmd\modref@varbasestyle |
| 711 |
% \makeatother, respectively) as a final argument, to define the ``global'' formatting which is to be used for the reference |
| 712 |
% regardless of which particular reference style (if any) is to be used. |
| 713 |
% We employ the standard strategy of appending a delimiter to the end of the argument, together with an unlikely terminal command |
| 714 |
% sequence. |
| 715 |
% \begin{macrocode} |
| 716 |
\def\ref##1{\modref@ref##1#1\egroup\modref@basestyle}% |
| 717 |
\def\varref##1{\modref@ref##1#1\egroup\modref@varbasestyle}% |
| 718 |
% \end{macrocode} |
| 719 |
% \end{macro} |
| 720 |
% \end{macro} |
| 721 |
% \begin{macro}{\modref@ref} |
| 722 |
% The command \makeatletter\cmd\modref@ref\makeatother\ attempts to split the argument into a prefix, delimiter, and suffix. |
| 723 |
% If the suffix is empty, the original argument to \cmd\ref\ had no delimiter (and thus indicates no style): in that case, |
| 724 |
% \makeatletter\cmd\modref@ref\makeatother\ invokes \makeatletter\cmd\@setref\makeatother\ on the reference, using the global |
| 725 |
% format specified in "##3" and the identity function as the ``style format''. |
| 726 |
% Otherwise, it passes it on to a second macro \makeatletter\cmd\modref@@ref\makeatother\ for further processing. |
| 727 |
% \begin{macrocode} |
| 728 |
\def\modref@ref##1#1##2\egroup##3{% |
| 729 |
\@ifempty{##2}{% |
| 730 |
\expandafter\@setref\csname r@##1\endcsname{##3\expandafter\@iden}{##1}% |
| 731 |
}{% |
| 732 |
\modref@@ref##1#1##2\egroup##3}}% |
| 733 |
% \end{macrocode} |
| 734 |
% \end{macro} |
| 735 |
% \begin{macro}{\modref@@ref} |
| 736 |
% Having been given an alleged style prefix, and a suffix making up the remainder of the reference label, the command |
| 737 |
% \makeatletter\cmd\modref@@ref\makeatother\ attempts to determine whether or not the prefix corresponds to a defined style. |
| 738 |
% We do this by testing for the existence of the command sequence "\modref@"<label-prefix>, which will be the macro which is |
| 739 |
% applied for that style. |
| 740 |
% If that macro does not exist, we invoke \makeatletter\cmd\@setref\makeatother\ on the reference, using the global |
| 741 |
% format specified in "##3" and the identity function as the ``style format''. |
| 742 |
% Otherwise, we obtain the command sequence for the reference's style-format, and invoke \makeatletter\cmd\@setref\makeatother\ |
| 743 |
% using the global format in "##3" and that style-format. |
| 744 |
% \begin{macrocode} |
| 745 |
\def\modref@@ref##1#1##2#1\egroup##3{% |
| 746 |
\@ifundefined{@modref@##1}{% |
| 747 |
\expandafter\@setref\csname r@##1#1##2\endcsname{% |
| 748 |
##3\expandafter\@iden}{##1#1##2}% |
| 749 |
}{% |
| 750 |
\expandafter\def\expandafter\@tempa\expandafter{% |
| 751 |
\csname @modref@##1\endcsname}% |
| 752 |
\expandafter\@setref\csname r@##1#1##2\endcsname{% |
| 753 |
##3\expandafter\@tempa}{##1#1##2}% |
| 754 |
}}% |
| 755 |
% \end{macrocode} |
| 756 |
% \end{macro} |
| 757 |
% |
| 758 |
% This completes the definition of \cmd\setrefdelimiter: it only remains to execute it for the delimiter which has been chosen. |
| 759 |
% This causes \cmd\ref\ to be redefined using the code above, using whatever string is contained in \makeatletter\cmd\modref@delimiter |
| 760 |
% \makeatother\ in the syntax of the definitions. |
| 761 |
% However, if the "delimiter" option was used, and set to the empty string for some reason, we produce an error. |
| 762 |
% \begin{macrocode} |
| 763 |
}% |
| 764 |
\ifx\modref@delimiter\@empty |
| 765 |
\modref@error{Option "delimiter" must be set to a non-empty value}{% |
| 766 |
The option "delimiter" was used, but seems to have been set to the |
| 767 |
empty string. I require a character, or a multi-character string, to |
| 768 |
delimit reference style names within cross-reference labels. If in |
| 769 |
doubt, just remove the "delimiter" option, and this should fix things.}% |
| 770 |
\else |
| 771 |
\expandafter\setrefdelimiter\expandafter{\modref@delimiter}% |
| 772 |
\fi |
| 773 |
% \end{macrocode} |
| 774 |
% \end{macro} |
| 775 |
% |
| 776 |
% \subsection{Defining global reference formats and special reference styles} |
| 777 |
% |
| 778 |
% \begin{macro}{\GlobalRefStyle} |
| 779 |
% \begin{macro}{\GlobalVarRefStyle} |
| 780 |
% We provide two commands for modifying the global format for \cmd\ref\ and \cmd\varref, each of which accept an argument describing |
| 781 |
% a two-argument macro. |
| 782 |
% They each create such a macro: these will be used to redefine \makeatletter\cmd\modref@basestyle\makeatother\ or |
| 783 |
% \makeatletter\cmd\modref@varbasestyle\makeatother. |
| 784 |
% \begin{macrocode} |
| 785 |
\newcommand\GlobalRefStyle[1]{\def\modref@@basestyle##1##2{#1}} |
| 786 |
\newcommand\GlobalVarRefStyle[1]{\def\modref@@varbasestyle##1##2{#1}} |
| 787 |
\@onlypreamble\GlobalRefStyle |
| 788 |
\@onlypreamble\GlobalVarRefStyle |
| 789 |
% \end{macrocode} |
| 790 |
% \end{macro} |
| 791 |
% \end{macro} |
| 792 |
% \begin{macro}{\modref@basestyle} |
| 793 |
% \begin{macro}{\modref@varbasestyle} |
| 794 |
% We have already met \makeatletter\cmd\modref@basestyle\makeatother\ and \makeatletter\cmd\modref@varbasestyle\makeatother, |
| 795 |
% which were used by \cmd\ref\ and \cmd\varref\ respectively; these commands are used to store the user-customizable ``global style'' |
| 796 |
% that gets applied to all references, whether or not they have a defined style type. |
| 797 |
% They both take three arguments: a macro to apply as a style type, and two more corresponding to the cross-reference value |
| 798 |
% and the page number of the reference. |
| 799 |
% They are designed in such a way that using the argument |
| 800 |
% \begin{center} |
| 801 |
% "{\modref@basestyle\expandafter\@modref@"<style-name>"}" |
| 802 |
% \end{center} |
| 803 |
% in place of \makeatletter\cmd\@firstoftwo\makeatother\ in a call to \makeatletter\cmd\@setref\makeatother, as in the original |
| 804 |
% definition of \cmd\ref\ in "latex.ltx", will have the effect of applying \makeatletter\cmd\modref@basestyle\makeatother\ to |
| 805 |
% precisely the specified style-format, and the cross-reference and page number. |
| 806 |
% It is easy to verify that this is exactly what is done in \makeatletter\cmd\modref@@ref\makeatother\ when called by the new |
| 807 |
% implementation of \cmd\ref; similar statements hold for \cmd\varref. |
| 808 |
% |
| 809 |
% We set \makeatletter\cmd\modref@basestyle\makeatother\ to apply the any format defined by \cmd\GlobalRefStyle, with the |
| 810 |
% styled reference as the first argument, and the page number as the second; and similarly for \makeatletter\cmd |
| 811 |
% \modref@varbasestyle\makeatother. |
| 812 |
% We then define the global reference format in each case to the identity function. |
| 813 |
% In the case where the style-format is replaced by the \makeatletter\cmd\@iden\makeatother\ macro, the effect of the |
| 814 |
% reference formatting then reduces the usage above to the traditional meaning of \cmd\ref, defined in terms of passing |
| 815 |
% the macro \makeatletter\cmd\@firstoftwo\makeatother\ to \makeatletter\cmd\@setref\makeatother. |
| 816 |
% \begin{macrocode} |
| 817 |
\def\modref@basestyle#1#2#3{\modref@@basestyle{#1{#2}}{#3}}% |
| 818 |
\def\modref@varbasestyle#1#2#3{\modref@@varbasestyle{#1{#2}}{#3}}% |
| 819 |
\GlobalRefStyle{#1}% |
| 820 |
\GlobalVarRefStyle{#1}% |
| 821 |
% \end{macrocode} |
| 822 |
% \end{macro} |
| 823 |
% \end{macro} |
| 824 |
% |
| 825 |
% \begin{macro}{\refstyle} |
| 826 |
% The \cmd\refstyle\ macro for defining particular reference styles takes a style-name <style-name> as its first argument, and |
| 827 |
% the formatting of the style as the second argument; the latter may use at most one argument, for the reference label. |
| 828 |
% The command \cmd\refstyle\ defines a command sequence \makeatletter\cmd\@modref@\makeatother<style-name> which takes one argument |
| 829 |
% and applies the required formatting. |
| 830 |
% In order to allow easy overriding of reference styles (\eg\ in order to redefine the formatting of \cmd\eqref\ when using the |
| 831 |
% "eqref" option), we do not require that reference style names be unique. |
| 832 |
% We require \cmd\refstyle\ to only be used in the document pre-amble; and if \cmd\refstyle\ is already defined, we produce an error. |
| 833 |
% \begin{macrocode} |
| 834 |
\edef\reserved@a{refstyle}% |
| 835 |
\@ifundefined\reserved@a{% |
| 836 |
\newcommand\refstyle[2]{% |
| 837 |
\expandafter\def\csname @modref@#1\endcsname##1{#2}}% |
| 838 |
}{% |
| 839 |
\modref@error{% |
| 840 |
Command \string\refstyle\ defined already; refer to the help message. |
| 841 |
}{% |
| 842 |
The "modref" package defines the command \string\refstyle; however, |
| 843 |
in this instance, \string\refstyle\ already had a meaning when "modref" |
| 844 |
started running. Please determine what is defining \string\refstyle, and |
| 845 |
whether you need it.}} |
| 846 |
% \end{macrocode} |
| 847 |
% \end{macro} |
| 848 |
% |
| 849 |
% \subsection{Customizing \cmd\eqref\ and displayed equation tags} |
| 850 |
% |
| 851 |
% \begin{macro}{\eqrefstyle} |
| 852 |
% \begin{macro}{\modref@trivbasestyle} |
| 853 |
% Changes to the style of \cmd\eqref\ can be made, independently of changes to the displayed equation tags, by redefining |
| 854 |
% \cmd\eqref\ to call the macro \makeatletter\cmd\modref@eqref\makeatother, and redefining that macro accordingly. |
| 855 |
% The way in which \cmd\eqref\ invokes \makeatletter\cmd\modref@eqref\makeatother\ is to use it as part of an argument to |
| 856 |
% \makeatletter\cmd\@setref\makeatother\ in such a way as to apply the style before resolving the reference (so that undefined |
| 857 |
% references will result in the output ``\ref{undef-reference}'' rather than a transformation of it). |
| 858 |
% However, we only redefine \cmd\eqref\ if \cmd\eqrefstyle\ is called, so that it retains the meaning given to it by "amsmath" |
| 859 |
% unless it is explicitly redefined. |
| 860 |
% We also define a ``trivial'' base style, \emph{\`a la} \makeatletter\cmd\modref@basestyle\makeatother, to facilitate this. |
| 861 |
% \begin{macrocode} |
| 862 |
\newcommand\eqrefstyle[1]{% |
| 863 |
\def\eqref##1{% |
| 864 |
\maketag@@@{% |
| 865 |
\expandafter\@setref\csname r@##1\endcsname{% |
| 866 |
\modref@trivbasestyle\expandafter\modref@eqref}{##1}}}% |
| 867 |
\def\modref@eqref##1{#1}}% |
| 868 |
\def\modref@trivbasestyle#1#2#3{#1{#2}} |
| 869 |
% \end{macrocode} |
| 870 |
% \end{macro} |
| 871 |
% \end{macro} |
| 872 |
% |
| 873 |
% \begin{macro}{\displaytagstyle} |
| 874 |
% To set the style of tags in displayed equations, we redefine the internal macro \makeatletter\cmd\tagform@\makeatother\ from |
| 875 |
% "amsmath.sty" to apply the style that we want, which will be defined by a macro \makeatletter\cmd\modref@tagstyle\makeatother. |
| 876 |
% \begin{macrocode} |
| 877 |
\newcommand\displaytagstyle[1]{% |
| 878 |
\def\modref@tagstyle##1{#1}% |
| 879 |
\def\tagform@##1{\maketag@@@{\modref@tagstyle{##1}}}% |
| 880 |
% \end{macrocode} |
| 881 |
% Because \cmd\eqref\ also uses the command \makeatletter\cmd\tagform@\makeatother\ for its implementation, a call to |
| 882 |
% \cmd\displayTagStyle\ also re-implements \cmd\eqref\ using \cmd\eqrefstyle\ --- but only if \cmd\eqref\ hasn't already |
| 883 |
% been re-implemented. |
| 884 |
% Whether or not it has is determined by testing if \makeatletter\cmd\modref@eqref\makeatother\ is well-defined. |
| 885 |
% The style that it sets is the original meaning of \cmd\eqref\ as defined in "amsmath.sty", except for expanding the macros |
| 886 |
% \makeatletter\cmd\tagform@\makeatother\ and \cmd\ref, and removing the macro \makeatletter\cmd\maketag@@@\makeatother\ |
| 887 |
% (which is already part of the new definition of \cmd\eqref). |
| 888 |
% \begin{macrocode} |
| 889 |
\@ifundefined{modref@eqref}{% |
| 890 |
\eqrefstyle{\textup{(\ignorespaces#1\unskip\@@italiccorr)}}% |
| 891 |
}\relax |
| 892 |
}% |
| 893 |
% \end{macrocode} |
| 894 |
% \end{macro} |
| 895 |
% |
| 896 |
% \Finale |
| 897 |
% |
| 898 |
% \section{Feedback} |
| 899 |
% |
| 900 |
% I would appreciate any feedback on this package that anyone may have, including error reports, |
| 901 |
% suggestions for modest extensions, and criticism (whether about the purpose or about the implementation |
| 902 |
% of the package). Please send your feedback to "[email protected]", with the phrase |
| 903 |
% ``\ModRef\ package'' (or something very similar) in the subject line. Thanks! |
| 904 |
\makeatother |
| 905 |
\endinput |
| 906 |
|
| 907 |
|
| 908 |
|
| 909 |
|