Debian Codegraph @

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

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