summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/prettyref/prettyref.dtx
blob: ceddb7fd169416e35bdc1dbb4125f50b6ba04a84 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
% \iffalse meta-comment
%%
%% prettyref v3.0
%%
%% Copyright 1995,1998.  by Kevin Ruland kevin@rodin.wustl.edu
%%
%% The following licence notice was added by Clea F. Rees on behalf of Kevin Ruland on 2008/11/05.
%%
%% prettyref consists of the files prettyref.dtx, prettyref.ins, prettyref.pdf, README and the derived file prettyref.sty. It is released to the public domain.
%%
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\usepackage{doc}
\CodelineNumbered
\begin{document}
  \DocInput{prettyref.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \fi
%
% \iffalse
%<*style>
% \fi
%
% \title{Improved reference formatting for \LaTeX2e}
%
% \author{Kevin S. Ruland}
%
% \maketitle
%
% There is a significant change to the newrefformat command in
% version~3.0. Please see the new discussion of that command below.
%
% This package has been completely reimplemented (in version 2.0).
% Please note the user level commands have changed syntax.  This was done
% because most of the packages providing hypertext/www functionality
% (such as, |hyper|, |hyperref| and |latex2html|)
% also modify the |\newlabel| structure.  In order to make this package
% compatable with those, I have decided not to change the |\newlabel|
% structure, but have the refence type stored in the label name.
%
% This package provides additional functionality to \LaTeX2e label--reference
% mechanism.   It allows the author to ``preformat'' all types of labels.
%
% A long standing problem with \LaTeX\ |\ref| command is that it only
% provides a raw number.  The author is responsible for properly formatting
% the number correctly.  For example, in order to correctly format a reference
% to an equation, the author must use |\textup{(\ref{eq:1})}|.  Or similarly
% for a figure, |Figure~(\ref{fig:2})|.  This way the ``format'' of the
% reference is hard coded into the paper.  If the author decides to change
% figure references to |Figure~\ref{fig:2}|, she must search and replace all
% the strings in the tex source.
%
% AMS\LaTeX\ has partially addressed this problem by providing the package
% |upref| and command |\eqref| in |amsmath|.  This is a partial solution
% for equation numbers and forces equation numbers in upright style.
%
% This package provides a more comprehensive solution by allowing the author
% to define various formats for the labels.  For example, to label a
% table the author would use |\label{tab:1}|.  To access the formatted
% reference the author uses |\prettyref{tab:1}|. |\pageref{tab:1}|
% and |\ref{tab:1}| work as usual.
%
% |\prettyref| is robust enough to be used within |\caption| and in
% |theorem| optional arguements.
%
% Labels in the document must be of the form |format:name| where the
% string |format| is used to determine the format.  Do not use the character
% |:| anywhere within the label except to seperate |format| from
% |name|.  |format:name| must be unique for it is used as the label.
%
%    \begin{macrocode}
\ProvidesPackage{prettyref}[1998/07/09 v3.0]
%    \end{macrocode}
%
% \DescribeMacro{\newrefformat}
% The command |\newrefformat| defines formats for pretty references.
%
% Usage: |\newrefformat{NAME}{FORMAT}|
%
% The |NAME| arguement is the name of the refernece type.
%
% The |FORMAT| argument is interpreted as the replacement text for
% an internal one-argument function.
% The |#1| will be replaced with the label name.
%    \begin{macrocode}
\def\newrefformat#1#2{%
  \@namedef{pr@#1}##1{#2}}
%    \end{macrocode}
%
% These define the default formats for table, eq, lemma, thm, section, and
% figure.  They also demonstrate the useage of |\newrefformat|.
%    \begin{macrocode}
\newrefformat{eq}{\textup{(\ref{#1})}}
\newrefformat{lem}{Lemma \ref{#1}}
\newrefformat{thm}{Theorem \ref{#1}}
\newrefformat{cha}{Chapter \ref{#1}}
\newrefformat{sec}{Section \ref{#1}}
\newrefformat{tab}{Table \ref{#1} on page \pageref{#1}}
\newrefformat{fig}{Figure \ref{#1} on page \pageref{#1}}
%    \end{macrocode}
%
% \DescribeMacro{\prettyref}
% The character |:| is used as a seperator.  It must be appended to
% the label string to terminate the |name| portion.
%
%    \begin{macrocode}
\def\prettyref#1{\@prettyref#1:}
%    \end{macrocode}
%
% \DescribeMacro{\@prettyref}
% The internal macro |\@prettyref| does all the work.  It takes two
% arguements delimited by |:|.  The first arguement is the format name.
% If the format has not been defined, a warning is issued and |\ref|
% is used.  Otherwise, the reference is formatted.  |\@prettyref|
% uses the \LaTeX\ macros |\ref| and |\pageref| to access the
% |\newlabel| data structure.  Hopefully this makes the package
% robust enough to use with various other pacakges.
%
%    \begin{macrocode}
\def\@prettyref#1:#2:{%
  \expandafter\ifx\csname pr@#1\endcsname\relax%
    \PackageWarning{prettyref}{Reference format #1\space undefined}%
    \ref{#1:#2}%
  \else%
    \csname pr@#1\endcsname{#1:#2}%
  \fi%
}
%    \end{macrocode}
%
% \endinput
%
\endinput
%</style>
%