3 % $Id: mdwref.dtx,v 1.3 2003/11/10 14:43:48 mdw Exp $
5 % Slightly fancy cross-referencing stuff
7 % (c) 2007 Mark Wooding
11 % \begin{meta-comment} <general public licence>
13 %% mdwref package -- slightly fancy cross-referencing stuff
14 %% Copyright (c) 2007 Mark Wooding
16 %% This program is free software; you can redistribute it and/or modify
17 %% it under the terms of the GNU General Public License as published by
18 %% the Free Software Foundation; either version 2 of the License, or
19 %% (at your option) any later version.
21 %% This program is distributed in the hope that it will be useful,
22 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
23 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 %% GNU General Public License for more details.
26 %% You should have received a copy of the GNU General Public License
27 %% along with this program; if not, write to the Free Software
28 %% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
32 % \begin{meta-comment} <Package preambles>
33 %<+package>\NeedsTeXFormat{LaTeX2e}
34 %<+package>\ProvidesPackage{mdwref}
35 %<+package> [2007/04/09 1.01 Cross-referencing]
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 \~}
56 % \begin{meta-comment}
60 \describespackage{mdwref}
67 %^^A-------------------------------------------------------------------------
69 % \section{User guide}
71 % I always name my cross-reference labels with a prefix telling me what kind
72 % of thing they are. A figure might be |fig:foo| or a table |tab:bar|. When
73 % I refer to the thing, then, I basically have to repeat myself:
74 % `|see table~\ref{tab:bar}|'. Kinda silly.
77 % The |\xref| command understands my prefixing system. I can say
78 % `|\xref{tab:bar}|' and it inserts a reference to `table~4', for example.
79 % This is, of course, useless if you want to put the reference at the
80 % beginning of a sentence: `Table~4 shows\dots'.
82 % The |\Xref| command (note the initial capital) handles this properly, so
83 % you just type `|\Xref{tab:bar} shows|\dots'.
85 % The full syntax of the |\xref| command is like this.
87 % <xref-command> ::= \[[
89 % \[ "[" <mangle> "]" \]
93 % The optional \<mangle> argument is a command to be applied to the generated
94 % text: it \emph{must} be a single token. Rather than printing `table', or
95 % whatever, it prints \syntax{<mangle>"{table}"}.
96 % The most obvious application of this is the |\Xref| command, which uses a
98 % \DescribeMacro\toupper
99 % The call \syntax{"\\toupper{"<stuff>"}"} typesets \<stuff> with the first
100 % character in uppercase. So |\Xref| is defined simply as\footnote{Modulo
101 % the fact that the author is a dreadful \TeX\ hacker.}
103 %\newcommand{\Xref}[1]{\xref[\toupper]{#1}}
106 % All that remains is to define the strings to be typeset for various kinds
108 % \DescribeMacro\defxref
109 % For this, we use the |\defxref| command:
111 % <definition> ::= \[[
117 % The \<prefix> is what you put on the front of your labels; the \<string> is
118 % the string to be typeset by |\xref|.
120 % A number of useful prefixes are already defined, following my usual
121 % preferences; they're shown in \xref{tab:defs}.
123 % \def\i#1#2{\texttt{#1}&\texttt{#2}\\}
124 % \begin{tabular}[C]{ll} \hlx*{hv}
125 % \textbf{Prefix} & \textbf{Text} \\ \hlx{vhv}
126 % \csname xref@defs\endcsname
127 % \hlx*{vh}\end{tabular}
128 % \caption{Predefined reference prefixes}
133 % \section{Implementation}
139 % The following quark will be useful.
141 \def\q@delim{\q@delim}
144 % \begin{macro}{\defxref}
145 % Defining prefixes is easy. We store the text for each prefix in a macro
146 % called \syntax{"\\xref$"<prefix>}. The only catch is that, for the
147 % purposes of generating \xref{tab:defs}, we maintain a list of the prefixes
148 % which have been defined so far, but this is fairly easy.
151 \toks@\expandafter{\xref@defs\i{#1}{#2}}\xdef\xref@defs{\the\toks@}%
152 \expandafter\def\csname xref$#1\endcsname{#2}%
155 % The list is obviously empty initially.
161 % \begin{macro}{\xref}
162 % We're meant to typeset a reference. The first job is to see whether
163 % there's an optional argument. If so, grab it; otherwise |\relax| will do.
165 \def\xref{\@ifnextchar[\xref@{\xref@[\relax]}}
166 \def\xref@[#1]#2{\xref@@{#1}#2:\q@delim:\q@delim:\q@delim\q@delim}
168 % Right; now we abuse \TeX's argument parser to pick apart the reference
169 % label, which ought to have the form \syntax{<prefix>":"<suffix>}.
171 \def\xref@@#1#2:#3:\q@delim#4\q@delim\q@delim{%
173 % So, |#1| is the optional command, or |\relax|. |#2| should be the
174 % prefix, and |#3| the suffix. However, if the string doesn't have any
175 % colons in, then |#3| will be |\q@delim|. This is easy to check for using
178 \def\@tempa{#2}\def\@tempb{#3}%
180 \PackageError{xref}{Bad ref syntax}%
182 \expandafter\let\expandafter\@tempa\csname xref$#2\endcsname%
184 \PackageError{xref}{Unknown ref kind `#2'}%
186 \toks@{#1}\toks\tw@\expandafter{\@tempa}%
187 \edef\next@{\the\toks@{\the\toks\tw@}}%
195 % \begin{macro}{\toupper}
196 % That's the difficult stuff done. Uppercasing is a matter of picking out
197 % the first letter and passing it to \TeX's |\uppercase| primitive.
199 \def\toupper#1{\toupper@#1}
200 \def\toupper@#1{\uppercase{#1}}
204 % \begin{macro}{\Xref}
205 % As promised, |\Xref| is very easy.
207 \def\Xref{\xref[\toupper]}
211 % Now all that remains is to initialize the table of prefix strings.
213 \defxref{ch}{chapter}
214 \defxref{app}{appendix}
215 \defxref{sec}{section}
216 \defxref{def}{definition}
217 \defxref{th}{theorem}
219 \defxref{prop}{proposition}
220 \defxref{cor}{corollary}
221 \defxref{fig}{figure}
223 \defxref{eq}{equation}
225 \defxref{ex}{exercise}
233 % \hfill Mark Wooding, \today