Debian Codegraph @

texmf-dist/source/latex/modref/modref.dtx

raw
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