% \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>
%