path: root/Master/texmf-dist/source/latex/fancyref/fancyref.dtx

%    \iffalse
%
% fancyref.dtx
% Docstrip archive, run through LaTeX.
%
% Copyright (C) 1999  Axel Reichert
% See the files README and COPYING.
%
%    \fi
%
%    \CheckSum{754}
%
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
%    \newcommand*{\ac}[1]{{\small #1}}
%    \newcommand*{\booktitle}[1]{\emph{#1}}
%    \newcommand*{\delimitor}[1]{\texttt{#1}}
%    \newcommand*{\env}[1]{\texttt{#1}}
%    \newcommand*{\error}[1]{\texttt{#1}}
%    \newcommand*{\file}[1]{\texttt{#1}}
%    \newcommand*{\format}[1]{\texttt{#1}}
%    \newcommand*{\frowney}{\texttt{)-:}}
%    \newcommand*{\labelname}[1]{\texttt{#1}}
%    \newcommand*{\mantitle}[1]{\emph{#1}}
%    \newcommand*{\option}[1]{\texttt{#1}}
%    \newcommand*{\package}[1]{\texttt{#1}}
%    \newcommand*{\person}[1]{\textsc{#1}}
%    \newcommand*{\prefix}[1]{\texttt{#1}}
%    \newcommand*{\sampleoutput}[1]{``#1''}
%    \newcommand*{\smiley}{\texttt{(-:}}
%    \newcommand*{\socalled}[1]{``#1''}
%    \newcommand*{\source}[1]{\texttt{#1}}
%    \newcommand*{\stringdef}[1]{``#1''}
%    \newcommand*{\winkey}{\texttt{(-;}}
%
%    \changes{v0.9b}{1999-02-02}{First release}
%    \changes{v0.9c}{1999-02-03}{%
%      Bug fixed in \fancyrefaddcaptions (\person{Felix Neubauer}%
%    }
%
%    \title{Fancy Cross-referencing}
%    \author{Axel Reichert}
%    \date{1999-02-03}
%    \maketitle
%    \begin{abstract}
%      \noindent
%      \file{fancyref.sty} is a package for fancy
%      cross-referencing. See the files \file{README} and
%      \file{COPYING} for additional information.
%    \end{abstract}
%    \tableofcontents
%
%
%    \section{Introduction}
%
%    Besides the notorious FAQ problem ``I get a section number when
%    refering to a figure!''\footnote{Just put \cmd{\label}
%    \emph{after} \cmd{\caption}.}, cross-referencing with \LaTeX{} is
%    simple:  You set a \cmd{\label} and refer to it with \cmd{\ref}
%    and \cmd{\pageref}.  These commands just work.
%
%    Some lazy people soon had the idea to write a \cmd{\fullref}
%    command to save some keystrokes:
%\begin{verbatim}
%   \newcommand*{\fullref}[1]{\ref{#1} on page~\pageref{#1}}
%\end{verbatim}
%    After that, people sometimes got page references to the current
%    page which cluttered the text with redundant information.
%
%    Perhaps one of these people was \person{Frank Mittelbach}, who
%    was so annoyed that he wrote the \package{varioref} package
%    \cite{Mittelbach:1998}.  It provides a  \cmd{\vref} command which
%    generates output dependent on the difference between the page
%    number of the label and the page number of the cross-reference,
%    e.\,g.\ like \sampleoutput{on the next page} or \sampleoutput{on
%    page~27}.  No output will be generated if label and
%    cross-reference fall onto the same page.  This is really great,
%    especially as the package supports lots of \emph{languages}.
%
%    If you write larger documents with lots of sections and figures,
%    you probably will find out that it is important to keep track of
%    your labels.  If you have a section labeled \labelname{britain}
%    and a figure labeled \labelname{england}, it is only a question
%    of time until you mix them up.  To avoid this, most people
%    \emph{prefix} the label with an abbreviation for the type of the
%    referenced object, e.\,g.\ \prefix{fig} is widely used for figure
%    labels.  Also it is common practice to separate this classifying
%    prefix from the label by a \emph{delimitor} character, normally
%    \delimitor{:} is used by convention
%    \cite[p.\,41]{Goossens:1994}.  If your labels look like
%    \labelname{sec:britain} or \labelname{fig:england} a mix-up will
%    belong to the past.
%
%    In almost all cases when you are referencing to a figure, you
%    will add a descriptive \emph{string} like \sampleoutput{Figure},
%    because the counter only is not very helpful to the
%    reader.  Hence, some people write macros for this purpose:
%\begin{verbatim}
%   \newcommand*{\figref}[1]{\figurename~\ref{#1}}
%\end{verbatim}
%    \cmd{\figurename} is much better than hard-coding
%    \sampleoutput{Figure} into the macro, because in this way the
%    command not only works in other languages, but also if you
%    redefine the string:
%\begin{verbatim}
%   \renewcommand*{\figurename}{Picture}
%\end{verbatim}
%    Both captions of figures and cross-references will now happily
%    use the new string.
%
%    In many journals cross-references to figures are emphasized by
%    usage of bold face or (much worse) underlining.  This enables the
%    reader (who is normally quickly browsing through an article) to
%    find the description of an interesting figure.  Of course you can
%    add a \cmd{\textbf} to the definition above, however, you will
%    run into trouble, if you want to use the \package{varioref}
%    package.  Neither
%\begin{verbatim}
%   \newcommand*{\figref}[1]{\textbf{\figurename~\vref{#1}}}
%\end{verbatim}
%    nor
%\begin{verbatim}
%   \newcommand*{\figref}[1]{\textbf{\figurename}~\vref{#1}}
%\end{verbatim}
%    will produce the desired output:  You will get
%    \sampleoutput{\textbf{\figurename~1 on page~2}} or
%    \sampleoutput{\textbf{\figurename}~1 on page~2} instead of
%    \sampleoutput{\textbf{\figurename~1} on page~2}.  What you can do
%    in this case is to hack the strings used by \file{varioref.sty},
%    e.\,g.\ like:
%\begin{verbatim}
%   \renewcommand*{\reftextfaraway}[1]{%
%     \normalfont on page~\pageref{#1}%
%   }
%\end{verbatim}
%    But this is dependent on the language and does not work within
%    italic text.
%
%    Also, you will not want bold face for every cross-reference to a
%    figure, only for the \socalled{main} cross-reference.  And you
%    will not want the page number to appear in every cross-reference
%    when explaining a picture consisting of subfigures:
%    \sampleoutput{The left part of Figure~1 on the following page
%    shows England.  The right part of Figure~1 on the next page shows
%    Great Britain.} So your set of macros will grow further by
%    \cmd{\mainfigref} and \cmd{\shortfigref}.  And of course the same
%    applies to tables as well.  Slowly, cross-referencing starts to
%    get messy~\ldots
%
%    Ok, you got the idea.  I felt the need for a more general
%    solution.  The \package{fancyref} package supports different
%    \emph{languages} (at the moment only english and german) and
%    allows customization of the classifying \emph{prefixes}, the
%    \emph{delimitor} character and the \emph{strings} used in
%    cross-references.  Most important, it provides user-definable
%    \emph{formats}.  Enough advocacy, here we go!
%
%
%    \section{Loading\label{sec:loading}}
%
%    You will need:
%    \begin{enumerate}
%    \item \LaTeXe{} (at least the 1995/06/01 release)
%    \item The \package{varioref} package (part of the standard
%      \LaTeX{} tools, normally included in every distribution)
%    \item The \package{german} or \package{babel} package
%      \cite{Raichle:1996, Braams:1997} (if you want to write not only
%      in english)
%    \end{enumerate}
%
%    The loading is simple:
%\begin{verbatim}
%   \usepackage{fancyref}
%\end{verbatim}
%    English is used as the default language.
%
%
%    \subsection{Language Options}
%
%    At the moment only english and german are supported languages,
%    others might follow.
%
%    If you write a german text:
%    \DescribeMacro{german}
%\begin{verbatim}
%   \usepackage{german} % \usepackage[german]{babel}
%   \usepackage[german]{fancyref}
%\end{verbatim}
%    \DescribeMacro{english}
%    If you write a mixed english/german text:
%\begin{verbatim}
%   \usepackage{german} % \usepackage[english,german]{babel}
%   \usepackage[english,german]{fancyref}
%\end{verbatim}
%    As with \file{babel.sty} the last language given in the optional
%    argument is the current language.  For \file{german.sty} you will
%    have to use the \cmd{\selectlanguage} command
%    \cite[p.\,7]{Raichle:1996} for english as current language.
%
%    Do \emph{not} pass the language as a global option to the
%    document class!  Due to a feature of the \LaTeX{} option handler
%\begin{verbatim}
%   \documentclass[english,danish]{article}
%   \usepackage{babel,fancyref}
%\end{verbatim}
%    will result in danish headings (\sampleoutput{Figur}) and english
%    strings for the  cross-references (\sampleoutput{Figure}),
%    without a warning or an error \cite[p.\,20]{LaTeX:1998}.  The
%    correct usage
%\begin{verbatim}
%   \documentclass{article}
%   \usepackage[english,danish]{babel,fancyref}
%\end{verbatim}
%    gives a package error, as expected, because danish is not (yet)
%    supported (see \fref{sec:names}).
%
%
%    \subsection{Spacing Options}
%
%    The spacing between the string and the counter can be adjusted,
%    see also \fref{sec:spacing}.
%
%    \DescribeMacro{loose}
%    Loose spacing, like in \sampleoutput{Figure~1}, which is the
%    default, can be turned on explicitly by:
%\begin{verbatim}
%   \usepackage[loose]{fancyref}
%\end{verbatim}
%    \DescribeMacro{tight}
%    Tight spacing, like in \sampleoutput{Figure\,1} will be obtained
%    with:
%\begin{verbatim}
%   \usepackage[tight]{fancyref}
%\end{verbatim}
%
%    Most textbooks on typography recommend loose spacing (i.\,e.\ a
%    normal word space) in this context, but tight spacing (half a
%    word space) is recommended in abbreviated formats like
%    \sampleoutput{Fig.\,1} \cite[p.\,220]{Willberg:1997}.
%
%
%    \subsection{Format Options}
%
%    The usage of page numbers for the cross-references can be
%    controlled by using different \package{fancyref} formats, see
%    \fref{sec:formats}.  The two most common variants are provided
%    also as package options.
%
%    \DescribeMacro{plain}
%    Output without a page number, like \sampleoutput{Figure~1}, is
%    used if the \option{plain} option is specified:
%\begin{verbatim}
%   \usepackage[plain]{fancyref}
%\end{verbatim}
%    \DescribeMacro{vario}
%    Output like from the \package{varioref} package
%    (\sampleoutput{Figure~1 on the following page}) is used by
%    default, but you could give the \option{vario} option
%    explicitely:
%\begin{verbatim}
%   \usepackage[vario]{fancyref}
%\end{verbatim}
%
%
%    \subsection{Hook Options}
%
%    The appearance of a cross-reference can not only be controlled by
%    individual formats
%    \marginpar{\raggedleft\footnotesize$\rightarrow$
%    Sec.\,\ref{sec:formats}, p.\,\pageref{sec:formats}} which depend
%    on the type of the referenced object, but also by a \emph{hook}
%    which is executed for \emph{every} cross-reference, see
%    \fref{sec:hooks}.  Two variants of  this hook can be activated by
%    package options (but only one at a time).
%
%    \DescribeMacro{margin}
%    You can place all cross-references into the margin, like
%    above.  This is achieved by:
%\begin{verbatim}
%   \usepackage[margin]{fancyref}
%\end{verbatim}
%    If you want to do this, you should be aware of the limited space
%    in the margin and use abbreviated formats.  In my opinion marginal
%    cross-references are sensible only for floats, for which I
%    already defined the \option{margin} formats
%    (see~\fref{sec:formats}), so this option should better  be
%    considered as an example of a hook.  The above example was indeed
%    done manually.  \winkey
%
%    \DescribeMacro{paren}
%    You can put all cross-references into parentheses, like this:
%    (\fref{sec:usage}).  This is achieved by:
%\begin{verbatim}
%   \usepackage[paren]{fancyref}
%\end{verbatim}
%    Neither use this option in combination with the \option{margin}
%    option nor with the \format{margin} formats!
%
%
%    \section{Usage\label{sec:usage}}
%
%    The cross-referencing is done by two almost identical macros.
%
%    \DescribeMacro{\fref}
%    \cmd{\fref} is used within a sentence and gives lower-case
%    output, like \sampleoutput{figure~1}.
%
%    \DescribeMacro{\Fref}
%    \cmd{\Fref} is used at the beginning of a sentence and gives
%    output with normal capitalization, like
%    \sampleoutput{Figure~1}.  For german users the macros make no
%    difference, \sampleoutput{Abbildung~1} remains
%    \sampleoutput{Abbildung~1} even within a sentence.  How sensible!
%    \winkey
%
%    There seems to be no reliable heuristic to determine the start of
%    a sentence, so you either have to cope with two macros or accept
%    \sampleoutput{Figure~1} even within a sentence.
%
%    Both macros take one optional argument, the format of the
%    cross-reference, and one mandatory argument, consisting of the
%    classifying prefix, the delimitor character and the label itself:
%    \begin{tabbing}
%      \small
%      |   \fref[|\meta{format}|]{|\meta{prefix}\meta{delim}\meta{label}|}| \\
%      \small
%      |   \Fref[|\meta{format}|]{|\meta{prefix}\meta{delim}\meta{label}|}|
%    \end{tabbing}
%    A typical cross-reference will thus look like this,
%\begin{verbatim}
%   \fref{fig:england}
%\end{verbatim}
%    with \prefix{fig} as the prefix, \delimitor{:} as the delimitor
%    and \labelname{britain} as the label, using the default
%    format.  The formats, the prefixes and the delimitor character are
%    described in detail in the following section.
%
%
%    \section{Customization}
%
%
%    \subsection{Prefixes\label{sec:prefixes}}
%
%    \DescribeMacro{\...labelprefix}
%    The following table shows the defaults of the various prefixes I
%    already defined for you.
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Object &
%          Macro &
%          Prefix \\
%        \hline
%          Chapter & \cmd{\fancyrefchaplabelprefix} &
%            \prefix{\fancyrefchaplabelprefix} \\
%          Section & \cmd{\fancyrefseclabelprefix} &
%            \prefix{\fancyrefseclabelprefix} \\
%          Equation & \cmd{\fancyrefeqlabelprefix} &
%            \prefix{\fancyrefeqlabelprefix} \\
%          Figure & \cmd{\fancyreffiglabelprefix} &
%            \prefix{\fancyreffiglabelprefix} \\
%          Table & \cmd{\fancyreftablabelprefix} &
%            \prefix{\fancyreftablabelprefix} \\
%          Enumeration & \cmd{\fancyrefenumlabelprefix} &
%            \prefix{\fancyrefenumlabelprefix} \\
%          Footnote & \cmd{\fancyreffnlabelprefix} &
%            \prefix{\fancyreffnlabelprefix} \\
%        \hline
%      \end{tabular}
%    \end{center}
%
%    If you need to add a prefix, use the following syntax:
%    \begin{tabbing}
%      \small
%      |   \newcommand*{|\meta{macro}|}{|\meta{prefix}|}|
%    \end{tabbing}
%    For example, if you need theorems in your document, you could
%    use:
%\begin{verbatim}
%   \newcommand*{\fancyrefthmlabelprefix}{thm}
%\end{verbatim}
%    Note that the name of the macro does not matter, but names
%    fitting into the scheme are highly recommended.  Be consistent.
%    After that, you will need to define your own \package{fancyref}
%    formats for the new prefixes.  Read \fref{sec:formats}.  And let me
%    know of objects for which I should supply prefixes.
%
%    \DescribeMacro{\...changeprefix}
%    If you need to change a prefix (either one I already provided or
%    one you added later), use the following syntax:
%    \begin{tabbing}
%      \small
%      |   \fancyrefchangeprefix{|\meta{macro}|}{|\meta{prefix}|}|
%    \end{tabbing}
%    For example, if you are labeling your equations with \prefix{eqn}
%    instead of \prefix{eq} (I guess this will be the most common
%    change):
%\begin{verbatim}
%   \fancyrefchangeprefix{\fancyrefeqlabelprefix}{eqn}
%\end{verbatim}
%
%
%    \subsection{Delimitors\label{sec:delimitors}}
%
%    \DescribeMacro{\fancyrefargdelim}
%    The default delimitor character is the colon (\delimitor{:}).  If
%    you need to change it, for example to \delimitor{-}, use the
%    following syntax:
%\begin{verbatim}
%   \renewcommand*{\fancyrefargdelim}{-}
%\end{verbatim}
%    There is no restriction to one character, you could also use
%    \delimitor{too-long}, but you definitely should use a delimitor
%    that never, ever occurs within the real label.  A single
%    \emph{letter} would be a very bad idea.
%
%
%    \subsection{Spacing\label{sec:spacing}}
%
%    \DescribeMacro{\...spacing}
%    Quite unlikely that someone is not happy with at least one of the
%    package options for this purpose, but one never knows~\ldots
%
%    The following table shows the definition of the spacing macros.
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Macro & Definition & Example \\
%        \hline
%          \cmd{\fancyrefloosespacing} & |~| &
%            \Freffigname\fancyrefloosespacing 1 \\
%          \cmd{\fancyreftightspacing} & \cmd{\,} &
%            \Freffigname\fancyreftightspacing 1 \\
%          \cmd{\fancyrefdefaultspacing} &
%            \cmd{\fancyrefloosespacing} &
%            \Freffigname\fancyrefdefaultspacing 1 \\
%        \hline
%      \end{tabular}
%    \end{center}
%
%    You could switch from loose to tight spacing and vice versa even
%    after the package is loaded:
%\begin{verbatim}
%   \renewcommand*{\fancyrefdefaultspacing}{%
%     \fancyreftightspacing
%   }
%\end{verbatim}
%
%    You could loosen the tight spacing or tighten the loose spacing
%    by using for example
%\begin{verbatim}
%   \renewcommand*{\fancyrefloosespacing}{\kern.25em}
%\end{verbatim}
%    but you should not change \cmd{\fancyrefdefaultspacing} in this
%    way, because you would lose flexibility:  Almost all
%    \package{fancyref} formats (except the \format{margin} formats)
%    use \cmd{\fancyrefdefaultspacing}, so it is clever to adjust
%    \cmd{\fancyreftightspacing} and \cmd{\fancyrefloosespacing} and
%    then to switch between the two variants.  But I doubt that this
%    will ever be necessary.
%
%
%    \subsection{Names\label{sec:names}}
%
%    \DescribeMacro{\...name}
%    The following table shows some strings that are already provided
%    by many document classes.  If they do not exist, I will define
%    them, otherwise I will not touch their values (in case you have
%    changed them already).
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Macro &
%          English string &
%          German string \\
%        \hline
%          \cmd{\chaptername} & \chaptername & Kapitel   \\
%          \cmd{\figurename}  & \figurename  & Abbildung \\
%          \cmd{\pagename}    & \pagename    & Seite     \\
%          \cmd{\tablename}   & \tablename   & Tabelle   \\
%        \hline
%      \end{tabular}
%    \end{center}
%
%    \DescribeMacro{\Fref...name}
%    The next table shows the strings used for cross-references at the
%    beginning of a sentence.
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Macro &
%          English string &
%          German string \\
%        \hline
%          \cmd{\Frefchapname} & \cmd{\chaptername} & \cmd{\chaptername} \\
%          \cmd{\Frefenumname} & \Frefenumname      & Punkt              \\
%          \cmd{\Frefeqname}   & \Frefeqname        & Gleichung          \\
%          \cmd{\Freffigname}  & \cmd{\figurename}  & \cmd{\figurename}  \\
%          \cmd{\Freffnname}   & \Freffnname        & Fu\ss note         \\
%          \cmd{\Frefonname}   & \Frefonname        & Auf                \\
%          \cmd{\Frefpgname}   & \cmd{\pagename}    & \cmd{\pagename}    \\
%          \cmd{\Frefsecname}  & \Frefsecname       & Abschnitt          \\
%          \cmd{\Frefseename}  & \Frefseename       & Siehe              \\
%          \cmd{\Freftabname}  & \cmd{\tablename}   & \cmd{\tablename}   \\
%        \hline
%      \end{tabular}
%    \end{center}
%
%    The \package{fancyref} package uss own macros to achieve maximum
%    flexibility:  If you redefine \cmd{\figurename} to
%    \stringdef{Picture}, both the caption and the cross-references
%    will use this string.  If brevity is more important to you than
%    consistency, you could also use \stringdef{Picture} within the
%    caption and \stringdef{Pic.} for the cross-references.  The
%    necessary code is:
%\begin{verbatim}
%   \renewcommand*{\figurename}{Picture}
%   \renewcommand*{\Freffigname}{Pic.}
%\end{verbatim}
%
%    \DescribeMacro{\fref...name}
%    Within a sentence you should use \stringdef{picture} instead of
%    \stringdef{Picture}.  The \package{fancyref} package takes care of
%    this for you and defines the corresponding macros
%    (\cmd{\fref...name}) with automatically generated lower-case
%    strings.
%
%    \DescribeMacro{\Frefonname}
%    \cmd{\Frefonname} and \cmd{\Frefseename} are not used by any
%    \package{fancyref} formats, but you could use them for your
%    additional formats.
%    \DescribeMacro{\Frefseename}
%    An interesting idea would be to use an arrow ($\mathsurround
%    0pt\rightarrow$) for \cmd{\Frefseename}:
%\begin{verbatim}
%   \renewcommand*{\Frefseename}{%
%     \ensuremath{\mathsurround 0pt\rightarrow}%
%   }
%\end{verbatim}
%    If do this, there will be no need to redefine \cmd{\frefseename}
%    manually, because the \cmd{\MakeLowercase} command
%    \cite[p.\,26]{LaTeX:1998} used internally to generate the
%    lower-case strings can cope even with such strange
%    things.  \smiley
%
%    \DescribeMacro{\Fref...shortname}
%    The table shows some abbreviated strings used for
%    cross-references with the \format{margin} formats.  I do not like
%    abbreviations very much,\footnote{I am stubborn, \person{Dirk},
%    am I not?  \winkey} because they need to be introduced carefully
%    (written out at the first occurrence) and even then make a
%    document less readable.  Also,  at the beginning of a sentence,
%    abbreviations should be written out, so you run into
%    inconsistencies (also known as trouble).  In my opinion they are
%    reasonable for the \format{margin} formats, so only the strings
%    necessary for these formats are defined.  If you are a big fan of
%    \ac{PCMCIA}\footnote{People Cannot Memorize Computer Industry's
%    Acronyms.} or abbreviations or simply do not bear my propaganda,
%    you are on your own.
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Macro &
%          English string &
%          German string \\
%        \hline
%          \cmd{\Freffigshortname} & \Freffigshortname & Abb. \\
%          \cmd{\Frefpgshortname}  & \Frefpgshortname  & S.   \\
%          \cmd{\Freftabshortname} & \Freftabshortname & Tab. \\
%        \hline
%      \end{tabular}
%    \end{center}
%    Lower-case versions of these strings (\cmd{\fref...shortname})
%    are generated automatically again.
%
%    \DescribeMacro{\...addcaptions}
%    If you add new prefixes (\fref{sec:prefixes}), you will probably
%    also need further strings, e.\,g.\ \cmd{\frefthmname}.  If you
%    write a multilingual document, they should automatically be
%    changed with the active language.  For this case the
%    \package{fancyref} package offers the following command,
%    \begin{tabbing}
%      \small
%      |   \fancyrefaddcaptions{|\meta{language}|}{|\meta{stringdefs}|}|
%    \end{tabbing}
%    which can be used only in the preamble of the document.  In the
%    above example you would use:
%\begin{verbatim}
%   \fancyrefaddcaptions{english}{%
%     \newcommand*{\Frefthmname}{Theorem}%
%     \newcommand*{\frefthmname}{%
%       \MakeLowercase{\Frefthmname}%
%     }%
%   }
%   \fancyrefaddcaptions{german}{%
%     \newcommand*{\Frefthmname}{Satz}%
%     \newcommand*{\frefthmname}{\Frefthmname}%
%   }
%\end{verbatim}
%    If you can supply such additional strings or further languages,
%    please do and send me a mail.
%
%
%    \subsection{Formats\label{sec:formats}}
%
%    The output of the \cmd{\fref} and \cmd{\Fref} commands depends on
%    the used \package{fancyref} format.  For all the different objects
%    that can be cross-referenced, two \package{fancyref} formats,
%    \format{plain} and \format{vario}, are already defined.  In
%    addition, for the floating objects (\env{figure} or \env{table}
%    environments) two other \package{fancyref} format called
%    \format{margin} and \format{main} are available.  The following
%    table shows sample output of these \package{fancyref} formats.
%    \begin{center}
%      \begin{tabular}{@{}lll@{}}
%        \hline
%          Object &
%          Format &
%          Output \\
%        \hline
%          Chapter & \prefix{vario} &
%            \frefchapname\fancyrefdefaultspacing 1 on the following page \\
%          & \prefix{plain} & \Frefchapname\fancyrefdefaultspacing 1 \\
%          Equation & \prefix{vario} &
%            \Frefeqname\fancyrefdefaultspacing (1) on the previous page \\
%          & \prefix{plain} & \frefeqname\fancyrefdefaultspacing (1) \\
%          Figure & \prefix{margin} & \footnotesize$\rightarrow$~%
%            \Freffigshortname\fancyreftightspacing 1,
%            p.\fancyreftightspacing 1 \\
%          & \prefix{main} &
%            \textbf{\freffigname\fancyrefdefaultspacing 1} on the
%            facing page \\
%          & \prefix{vario} & \Freffigname\fancyrefdefaultspacing 1 on
%            the page before \\
%          & \prefix{plain} & \freffigname\fancyrefdefaultspacing 1 \\
%        \hline
%      \end{tabular}
%    \end{center}
%    The \package{fancyref} formats for sections, enumerations and
%    footnotes give output similar to those for chapters, whereas the
%    formats for tables correspond to the \package{fancyref} formats
%    for figures.
%
%    \DescribeMacro{\...defaultformat}
%    If no optional argument is specified for the \cmd{\fref} or
%    \cmd{\Fref} command, the \format{vario} format will be used.  You
%    can change this default \package{fancyref} format to
%    \format{plain}:
%\begin{verbatim}
%   \renewcommand{\fancyrefdefaultformat}{plain}
%\end{verbatim}
%
%    If you do not like some of these \package{fancyref} formats or
%    you need some more, e.\,g.\ for theorems, algorithms etc., you
%    will have to define them yourself.  If you define some nice
%    formats, please let me know, perhaps I will add them in a future
%    version of this package.
%
%    \DescribeMacro{\frefformat}
%    The definition is done by means of two almost identical
%    macros.  \cmd{\frefformat} declares (or changes) the formats used
%    within a
%    \DescribeMacro{\Frefformat}
%    sentence, whereas \cmd{\Frefformat} does the same for the formats
%    used at the beginning of a sentence.  Unfortunately this means
%    that you need to do the work twice.  \frowney
%
%    Both macros take three mandatory arguments, the name of the
%    \package{fancyref} format, the prefix macro and the description
%    of the format itself:
%    \begin{tabbing}
%      \small
%      |   \frefformat{|\meta{format}|}{|\meta{prefix macro}\meta{output}|}| \\
%      \small
%      |   \Frefformat{|\meta{format}|}{|\meta{prefix macro}\meta{output}|}|
%    \end{tabbing}
%    Within the third argument |#1| will be replaced by the counter of
%    the referenced object (i.\,e.\ the output of a \cmd{\ref}
%    command), |#2| will be replaced by the page number (i.\,e.\ the
%    output of a \cmd{\pageref} command) and |#3| will be replaced by
%    the output of a \cmd{\vpageref} command (\sampleoutput{on the
%    facing page}, \sampleoutput{on page~1}).
%
%    As an example, I will modify the output foss-references to
%    figures done with the \format{main} format:
%\begin{verbatim}
%   \frefformat{main}{\fancyreffiglabelprefix}{%
%     \MakeUppercase{\freffigname}\fancyrefdefaultspacing#1#2%
%   }%
%   \Frefformat{main}{\fancyreffiglabelprefix}{%
%     \MakeUppercase{\Freffigname}\fancyrefdefaultspacing#1#2%
%   }%
%\end{verbatim}
%    These redefinitions will make |\fref[main]{fig:foo}| come out as
%    \sampleoutput{FIGURE~1 on page~1}.  The page number will always be
%    printed explicitly, not like \file{varioref.sty} output.  By use
%    of the \cmd{\freffigname}, \cmd{\Freffigname} and
%    \cmd{\fancyrefdefaultspacing} commands it is ensured that further
%    modifications of the string as well as the spacing and language
%    options of the package will work.  A quick and dirty hack would
%    have been:
%\begin{verbatim}
%   \frefformat{main}{\fancyreffiglabelprefix}{FIGURE~#1#2}
%   \Frefformat{main}{\fancyreffiglabelprefix}{FIGURE~#1#2}
%\end{verbatim}
%
%    The usage of the defined macros for spacing and naming like in
%    the first example is of course highly recommended.  Do not blame
%    me, if your lazyness leads to inconsistencies.  \winkey
%
%    Note that in either case you \emph{must} use the prefix
%    \emph{macro}, not the string itself!
%
%
%    \subsection{Hooks\label{sec:hooks}}
%
%    \DescribeMacro{\fancyrefhook}
%    After all the work of the \package{fancyref} formats has been
%    done, the result is passed as an argument to a hook command
%    called \cmd{\fancyrefhook}.  Normally, this hook does nothing but
%    simply passing on the output.  If you want to change this hook,
%    use the following syntax:
%    \begin{tabbing}
%      \small
%      |   \renewcommand{\fancyrefhook}[1]{|\meta{definition}|}|
%    \end{tabbing}
%    Within \meta{definition}, |#1| will be replaced by the output of
%    the \package{fancyref} format.
%
%    You can use this hook for all kinds of weird stuff, e.\,g.\ if
%    you want to have huge cross-references, use the following code:
%\begin{verbatim}
%   \renewcommand*{\fancyrefhook}[1]{{\huge #1}}
%\end{verbatim}
%    In this simple example the |*|-form of \cmd{\renewcommand} may be
%    used, because the hook does not contain whole paragraphs
%    \cite[p.\,14]{LaTeX:1997}.  This makes debugging of your code
%    easier.
%
%    A more complex (and totally brain-dead) example does not work
%    with the |*|-form:
%\begin{verbatim}
%   \renewcommand{\fancyrefhook}[1]{%
%     \begin{itemize}%
%       \item #1%
%     \end{itemize}%
%   }
%\end{verbatim}
%    If you define really \emph{useful} and \socalled{typographically
%    correct} hooks, please send me a mail, so I can include your work
%    in future versions of this package.  \winkey
%
%
%    \section{Examples}
%
%    See the example file \file{freftest.tex} and its output,
%    \file{freftest.dvi}.
%
%
%    \section{Bugs}
%
%    None, as my beta testers, \person{Dirk Kuypers} and
%    \person{Robin~S.~Socha}, told me.  \winkey
%
%    If you encounter problems after having changed all your
%    cross-references to the macros provided by \file{fancyref.sty},
%    please go through the following checklist:
%    \begin{enumerate}
%    \item Make sure that you either use \delimitor{:} as a delimitor
%      or that have changed it as described in \fref{sec:delimitors}.
%    \item Make sure that you either use the default prefixes or that
%      you have changed them as described in
%      \fref{sec:prefixes}.  Especially do \emph{not} try to modify the
%      prefixes with the \cmd{\renewcommand} command.
%    \item Make sure that you have defined all necessary formats in
%      addition to those provided by me.  The definition of
%      \package{fancyref} formats is described in \fref{sec:formats}.
%    \item Make sure that you have eliminated all old superfluous
%      strings like \source{Figure} or \cmd{\figurename} in your source
%      code.  Just replacing all \cmd{\ref} commands with \cmd{\fref}
%      will \emph{not} be sufficient.
%    \end{enumerate}
%
%    As far as I know, there is only one \emph{real} problem:  If you
%    are working on a multi-author document where each author is used
%    to a different set of prefixes and prefers a different delimitor,
%    be \emph{extremely cautious} when redefining the prefixes and the
%    delimitor.  You will get really funny errors, if the current
%    delimitor is \delimitor{-}, the prefix for equations is
%    \prefix{eqn} and you try to make a cross-reference to an equation
%    in a part written by another author who used \delimitor{:} and
%    \prefix{eq} in his \cmd{\label} commands.
%
%    With the current implementation the only solution is to
%    temporarily redefine the prefix and the deliminator, do the
%    cross-reference and switch back to the original definitions
%    again.  This is annoying, of course.  \frowney
%
%    As a consequence, I would recommend either to drop this
%    cross-reference or to try to convince your co-authors that your
%    prefixes and delimitor are the best.  Sorry.
%
%
%    \section{Implementation}
%
%
%    \subsection{Documentation Driver}
%
%    \begin{macrocode}
%<*driver>
\documentclass[12pt,a4paper]{ltxdoc} \usepackage{fancyref}
\begin{document}
  \DocInput{fancyref.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%    \StopEventually{
%      \font\logosl=logosl10 scaled\magstep1
%      \begin{thebibliography}{1}
%      \bibitem{AMS:1996}
%        American Mathematical Society.
%        \newblock \mantitle{$\cal{AMS}$-\LaTeX{} Version~1.2 User's
%        Guide}, Nov.~1996.
%        \newblock Version~1.02.
%      \bibitem{Braams:1997}
%        \person{Braams,~J.}:  \mantitle{Babel, a multilingual package for
%        use with \LaTeX's standard document classes}.
%        \newblock Zoetermeer, Jan.~1997.
%      \bibitem{Franz:1998}
%        \person{Franz,~M.}:  \mantitle{The \package{soul} package}, Dec.~1998.
%        \newblock Version~1.1a.
%      \bibitem{Goossens:1994}
%        \person{Goossens,~M.; Mittelbach,~F.; Samarin,~A.}:  \booktitle{Der
%        \LaTeX-Begleiter}.
%        \newblock Addison-Wesley, Bonn, 1st~edn., 1994.
%      \bibitem{LaTeX:1997}
%        \LaTeX3 Project Team.
%        \newblock \mantitle{\LaTeXe{} for authors}, Jun.~1997.
%      \bibitem{LaTeX:1998}
%        \LaTeX3 Project Team.
%        \newblock \mantitle{\LaTeXe{} for class and package writers},
%        Jun.~1998.
%      \bibitem{Mittelbach:1998}
%        \person{Mittelbach,~F.}:  \mantitle{The \package{varioref} package}.
%        \newblock Mainz, May~1998.
%        \newblock Version~1.1g.
%      \bibitem{Raichle:1996}
%        \person{Raichle,~B.}:
%        \mantitle{Kurzbeschreibung~--~\file{german.sty} (Version~2.5)}.
%        \newblock Deutschsprachige Anwendervereinigung \TeX{}~e.\,V.,
%        May~1996.
%        \newblock Version~2.5c.
%      \bibitem{Willberg:1997}
%        \person{Willberg,~H.\,P.; Forssman,~F.}:
%        \booktitle{Lesetypographie}.
%        \newblock Hermann Schmidt, Mainz, 1997.
%      \end{thebibliography}
%    }
%
%
%    \subsection{\file{fancyref.sty}}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
%    \subsubsection{Identification}
%
%    As this package uses the \cmd{\MakeLowercase} command, it does
%    not work with older \LaTeXe{} versions.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1995/06/01]%
%    \end{macrocode}
%    The package identifies itself with its release date, a version
%    number and a short description.
%    \begin{macrocode}
\ProvidesPackage{fancyref}[%
  1999/02/03 v0.9c Fancy cross-referencing%
]%
%    \end{macrocode}
%
%
%    \subsubsection{Initialization}
%
%    \begin{macro}{\@fancyref@add@to}
%    This macro is adapted from \file{babel.def}.  If a command (the
%    first argument) is undefined, it will be defined by the content
%    of the second argument.  If the command is defined already, the
%    content of the second argument will be appended to the old
%    definition of the command.  The macro will be used to add further
%    definitions to the \cmd{\captions...} commands provided by the
%    \package{babel}~package or \file{german.sty}.
%    \begin{macrocode}
\newcommand*{\@fancyref@add@to}[2]{%
  \ifx#1\@undefined
    \newcommand*{#1}{#2}%
  \else
    \ifx#1\relax
      \newcommand*{#1}{#2}%
    \else
      \bgroup
        \toks@\expandafter{#1#2}%
        \xdef#1{\the\toks@}%
      \egroup
    \fi
  \fi
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\...addcaptions}
%    This macro adds strings (the second argument) to the
%    \cmd{\captions...} commands\footnote{Credits go to \person{Bernd
%    Raichle} who told me how to do this in a politically correct
%    way.} provided by the \package{babel} package or
%    \file{german.sty}, or it simply defines these new strings.  The
%    name of the language is given in the first argument.
%
%    To make the new strings become effective, the current language is
%    saved\footnote{Credits go to \person{Felix Neubauer}, who pointed
%    out that this should be done in a temporary command rather than
%    a token register to avoid an error in combination with
%    \file{babel.sty} or \file{german.sty} and automatically
%    generated lists like the \file{toc}, \file{lof} or \file{lot}
%    files.} at the beginning of the document, the code defining the
%    strings is executed and the language for the captions is
%    switched back again. 
%    \begin{macrocode}
\newcommand*{\@fancyref@temp}{\@empty}%
\newcommand*{\fancyrefaddcaptions}[2]{%
  \@ifundefined{captions#1}{%
    #2%
  }{%
    \expandafter
      \@fancyref@add@to\csname captions#1\endcsname{#2}%
    \AtBeginDocument{%
      \let\@fancyref@temp=\languagename
      \csname captions#1\endcsname
      \csname captions\@fancyref@temp\endcsname
      \let\@fancyref@temp=\@empty
    }%
  }%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\fancyrefhook}
%    \label{sec:fancyrefhook}
%    It may be clever to define a hook that is executed for every
%    \cmd{\fref} or \cmd{\Fref} command.  For the moment the hook does
%    nothing but simply inserting its argument.  I will do something
%    more useful with it later in this file.  \emph{You} can use it
%    also for the way of cross-referencing the world is waiting for.
%    \winkey
%
%    Send me a mail, if you think you have defined a really nifty
%    hook, so I can include it in future versions of this package.
%    \begin{macrocode}
\newcommand*{\fancyrefhook}[1]{#1}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\...spacing}
%    These two macros are used to define the spacing between the type
%    of the referenced object and the counter of the object, for
%    example between \sampleoutput{Figure} and \sampleoutput{1} in
%    \sampleoutput{Figure~1}.  Normally there is no need to change
%    these definitions.
%    \begin{macrocode}
\newcommand*{\fancyrefloosespacing}{~}%
\newcommand*{\fancyreftightspacing}{\,}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\...defaultformat}
%    Now the default \package{fancyref} format is initialized.  The
%    real value will be set later depending on the package options.
%    \begin{macrocode}
\newcommand*{\fancyrefdefaultformat}{\@empty}%
%    \end{macrocode}
%    \end{macro}
%    Now some strings are initialized.  The real values will be
%    declared later depending on the package options.
%    \begin{macrocode}
\newcommand*{\Frefchapname}{\@empty}%
\newcommand*{\Frefenumname}{\@empty}%
\newcommand*{\Frefeqname}{\@empty}%
\newcommand*{\Freffigname}{\@empty}%
\newcommand*{\Freffnname}{\@empty}%
\newcommand*{\Frefonname}{\@empty}%
\newcommand*{\Frefpgname}{\@empty}%
\newcommand*{\Frefsecname}{\@empty}%
\newcommand*{\Frefseename}{\@empty}%
\newcommand*{\Freftabname}{\@empty}%
\newcommand*{\Freffigshortname}{\@empty}%
\newcommand*{\Frefpgshortname}{\@empty}%
\newcommand*{\Freftabshortname}{\@empty}%
\newcommand*{\frefchapname}{\@empty}%
\newcommand*{\frefenumname}{\@empty}%
\newcommand*{\frefeqname}{\@empty}%
\newcommand*{\freffigname}{\@empty}%
\newcommand*{\freffnname}{\@empty}%
\newcommand*{\frefonname}{\@empty}%
\newcommand*{\frefpgname}{\@empty}%
\newcommand*{\frefsecname}{\@empty}%
\newcommand*{\frefseename}{\@empty}%
\newcommand*{\freftabname}{\@empty}%
\newcommand*{\freffigshortname}{\@empty}%
\newcommand*{\frefpgshortname}{\@empty}%
\newcommand*{\freftabshortname}{\@empty}%
%    \end{macrocode}
%
%
%    \subsubsection{Option Declaration}
%
%    \DescribeMacro{english}
%    Now the package options are declared.  Send me a mail, if you
%    define options for other languages than english or german.
%    \begin{macrocode}
\DeclareOption{english}{%
%    \end{macrocode}
%    Some strings for cross-referencing in english are added (if the
%    command \cmd{\captionsenglish} is existing) or simply defined.
%    \begin{macrocode}
  \fancyrefaddcaptions{english}{%
%    \end{macrocode}
%    I better do not touch these strings, because they are used in
%    many document classes and may be already changed by the user.
%    Therefore they will be defined only if they did not exist before
%    \cite{LaTeX:1997}.
%    \begin{macrocode}
    \providecommand*{\chaptername}{Chapter}%
    \providecommand*{\figurename}{Figure}%
    \providecommand*{\pagename}{Page}%
    \providecommand*{\tablename}{Table}%
%    \end{macrocode}
%    \begin{macro}{\Fref...name}
%    The \package{fancyref} package uses its own strings for
%    cross-referencing purposes.  In this way you can use
%    \stringdef{Chapter} for chapter headings but \stringdef{Chap.}
%    for cross-referencing.
%
%    However, I do not recommend abbreviations for cross-references,
%    because they look ugly at the beginning of a sentence and should
%    be avoided in these places according to most typographers.  Also,
%    the scientific publisher Springer does not allow abbreviation of
%    the words \sampleoutput{table} or \sampleoutput{Tabelle} (I
%    suppose because of ambuigity with \sampleoutput{tabbing} or
%    \sampleoutput{Tabulator}).
%
%    The macros \cmd{\Frefonname} and \cmd{\Frefseename} may be useful
%    in new, user-defined \package{fancyref} formats
%    (\frefseename~\frefpgname~\pageref{sec:fancyrefformats}).
%
%    All macro names start with a capital \source{S}, because they
%    will be used for cross-references at the beginning of a sentence,
%    where usually capital letters are used.
%    \begin{macrocode}
    \renewcommand*{\Frefchapname}{\chaptername}%
    \renewcommand*{\Frefenumname}{Item}%
    \renewcommand*{\Frefeqname}{Equation}%
    \renewcommand*{\Freffigname}{\figurename}%
    \renewcommand*{\Freffnname}{Footnote}%
    \renewcommand*{\Frefonname}{On}%
    \renewcommand*{\Frefpgname}{\pagename}%
    \renewcommand*{\Frefsecname}{Section}%
    \renewcommand*{\Frefseename}{See}%
    \renewcommand*{\Freftabname}{\tablename}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\Fref...shortname}
%    These macros are used for cross-references placed in the margin.
%    In marginal notes compact information is crucial due to the
%    limited space, so abbreviated versions of the strings are used.
%    For my general opinion about abbreviations see above.
%    \begin{macrocode}
    \renewcommand*{\Freffigshortname}{Fig.}%
    \renewcommand*{\Frefpgshortname}{P.}%
    \renewcommand*{\Freftabshortname}{Tab.}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\fref...name}
%    Now the lower-case versions of the language dependent strings
%    (starting with a lower-case \source{s}) are declared.  As these
%    macros are generated automatically by use of the
%    \cmd{\MakeLowercase} command, there is no need to customize them,
%    except you want to use for example \stringdef{Table} at the start
%    of a sentence and \stringdef{tabular} within a sentence.
%    Inconsistencies like this should of course be avoided.
%    \begin{macrocode}
    \renewcommand*{\frefchapname}{%
      \MakeLowercase{\Frefchapname}%
    }%
    \renewcommand*{\frefenumname}{%
      \MakeLowercase{\Frefenumname}%
    }%
    \renewcommand*{\frefeqname}{%
      \MakeLowercase{\Frefeqname}%
    }%
    \renewcommand*{\freffigname}{%
      \MakeLowercase{\Freffigname}%
    }%
    \renewcommand*{\freffnname}{%
      \MakeLowercase{\Freffnname}%
    }%
    \renewcommand*{\frefonname}{%
      \MakeLowercase{\Frefonname}%
    }%
    \renewcommand*{\frefpgname}{%
      \MakeLowercase{\Frefpgname}%
    }%
    \renewcommand*{\frefsecname}{%
      \MakeLowercase{\Frefsecname}%
    }%
    \renewcommand*{\frefseename}{%
      \MakeLowercase{\Frefseename}%
    }%
    \renewcommand*{\freftabname}{%
      \MakeLowercase{\Freftabname}%
    }%
    \renewcommand*{\freffigshortname}{%
      \MakeLowercase{\Freffigshortname}%
    }%
    \renewcommand*{\frefpgshortname}{%
      \MakeLowercase{\Frefpgshortname}%
    }%
    \renewcommand*{\freftabshortname}{%
      \MakeLowercase{\Freftabshortname}%
    }%
%    \end{macrocode}
%    \end{macro}
%    The closing brace of the second argument of \cmd{\fancyrefaddto}:
%    \begin{macrocode}
  }%
%    \end{macrocode}
%    If \cmd{\captionsenglish} is defined (\file{babel.sty} or
%    \file{german.sty} are used), the language is switched to
%    \option{english}.  In either case the \package{varioref} package
%    will be called with the option \option{english} to provide
%    english strings like \sampleoutput{on the following page}, see
%    \file{varioref.dvi}.
%    \begin{macrocode}
  \@ifundefined{captionsenglish}{%
  }{%
    \selectlanguage{english}%
  }%
  \PassOptionsToPackage{\CurrentOption}{varioref}%
%    \end{macrocode}
%    The closing brace of the \option{english} option:
%    \begin{macrocode}
}%
%    \end{macrocode}
%    \DescribeMacro{german}
%    The definition of the german strings is more simple.  Except for
%    \cmd{\Frefonname} and \cmd{\Frefseename} the lower-case versions
%    of the macros are identical with the upper-case version.  Damn,
%    my mother tongue seems to be a rather simple language.  \winkey
%
%    A check for the existence of \cmd{\captionsgerman} should not be
%    necessary as in almost all cases german \LaTeX nicians use either
%    \file{babel.sty} or \file{german.sty}, but one never
%    knows~\ldots{} The language is switched and the
%    \package{varioref} package is prepared accordingly.
%    \begin{macrocode}
\DeclareOption{german}{%
  \fancyrefaddcaptions{german}{%
    \providecommand*{\chaptername}{Kapitel}%
    \providecommand*{\figurename}{Abbildung}%
    \providecommand*{\pagename}{Seite}%
    \providecommand*{\tablename}{Tabelle}%
    \renewcommand*{\Frefchapname}{\chaptername}%
    \renewcommand*{\Frefenumname}{Punkt}%
    \renewcommand*{\Frefeqname}{Gleichung}%
    \renewcommand*{\Freffigname}{\figurename}%
    \renewcommand*{\Freffigshortname}{Abb.}%
    \renewcommand*{\Freffnname}{Fu\ss note}%
    \renewcommand*{\Frefonname}{Auf}%
    \renewcommand*{\Frefpgname}{\pagename}%
    \renewcommand*{\Frefpgshortname}{S.}%
    \renewcommand*{\Frefsecname}{Abschnitt}%
    \renewcommand*{\Frefseename}{Siehe}%
    \renewcommand*{\Freftabname}{\tablename}%
    \renewcommand*{\Freftabshortname}{Tab.}%
    \renewcommand*{\frefchapname}{\Frefchapname}%
    \renewcommand*{\frefenumname}{\Frefenumname}%
    \renewcommand*{\frefeqname}{\Frefeqname}%
    \renewcommand*{\freffigname}{\Freffigname}%
    \renewcommand*{\freffigshortname}{\Freffigshortname}%
    \renewcommand*{\freffnname}{\Freffnname}%
    \renewcommand*{\frefonname}{%
      \MakeLowercase{\Frefonname}%
    }%
    \renewcommand*{\frefpgname}{\Frefpgname}%
    \renewcommand*{\frefpgshortname}{\Frefpgshortname}%
    \renewcommand*{\frefsecname}{\Frefsecname}%
    \renewcommand*{\frefseename}{%
      \MakeLowercase{\Frefseename}%
    }%
    \renewcommand*{\freftabname}{\Freftabname}%
    \renewcommand*{\freftabshortname}{\Freftabshortname}%
  }%
  \@ifundefined{captionsgerman}{%
  }{%
    \selectlanguage{german}%
  }%
  \PassOptionsToPackage{\CurrentOption}{varioref}%
}%
%    \end{macrocode}
%    \DescribeMacro{loose}
%    This option sets up loose spacing between string and counter like
%    \sampleoutput{Figure~1}.  This spacing is recommended, because
%    \file{varioref.sty} is using it also (on a hard-coded base), and
%    so inconsistencies can be avoided.  Do not take things too
%    seriously, the inter-word spacing varies quite a bit from line to
%    line.  Even a trained eye will not always be able to distinguish
%    between \socalled{tight} and \socalled{loose} spacing.  Compared
%    with favourite \ac{WYTYSYDG}\footnote{What You Thought You Saw
%    You Didn't Get.} word processors the spacing will be tight in
%    either case.  \winkey
%    \begin{macrocode}
\DeclareOption{loose}{%
  \newcommand*{\fancyrefdefaultspacing}{%
    \fancyrefloosespacing
  }%
}%
%    \end{macrocode}
%    \DescribeMacro{margin}
%    This option is an example for a application of
%    \cmd{\fancyrefhook}.  It places all cross-references into the
%    margin, typesetting them in \cmd{\footnotesize} and
%    \cmd{\raggedright}.  For details see the definition of the
%    \format{margin} format \vpageref{sec:margin}.
%
%    Do \emph{not} use the \option{margin} option in combination with
%    those \format{margin} formats.  As this would need nested
%    \cmd{\marginpar} commands, you will get \error{Float(s) lost.}
%    error messages.
%
%    Also, you should use abbreviated formats in combination with the
%    \option{margin} option, because there is not enough space for a
%    message like \sampleoutput{Figure~1 on the following page} out
%    there.
%
%    I would recommend the usage of marginal cross-references only for
%    floats.  The according formats are already defined, so take this
%    options as an example for what is possible.
%    \begin{macrocode}
\DeclareOption{margin}{%
  \renewcommand{\fancyrefhook}[1]{%
    \mbox{}%
    \marginpar{%
      \raggedright\hspace{0pt}\footnotesize
      \ensuremath{\m@th\rightarrow}~#1%
    }%
  }%
}%
%    \end{macrocode}
%    \DescribeMacro{paren}
%    Another example for an application of \cmd{\fancyrefhook}.  It
%    simply puts parentheses around every cross-reference.  This does
%    not make much sense, if you intend to use marginal notes for
%    cross-referencing purposes:  If you combine this option with the
%    |margin| option, the last specified option \socalled{wins}.  If
%    you use the \format{margin} formats defined later, you will get
%    parentheses around marginal notes, which is ugly.
%    \begin{macrocode}
\DeclareOption{paren}{%
  \renewcommand*{\fancyrefhook}[1]{(#1)}%
}%
%    \end{macrocode}
%    \DescribeMacro{plain}
%    If this package option is given, only the plain counter of the
%    referenced object will be used, no page number will be printed at
%    all.
%    \begin{macrocode}
\DeclareOption{plain}{%
  \renewcommand*{\fancyrefdefaultformat}{plain}%
}%
%    \end{macrocode}
%    \DescribeMacro{tight}
%    This option may be useful, if you prefer tight spacing between
%    string and counter.  According to most textbooks on typography
%    this is the recommended spacing between parts of abbreviations
%    like \sampleoutput{i.\,e.} or \sampleoutput{Fig.\,1}.
%    \begin{macrocode}
\DeclareOption{tight}{%
  \newcommand*{\fancyrefdefaultspacing}{%
    \fancyreftightspacing
  }%
}%
%    \end{macrocode}
%    \DescribeMacro{vario}
%    If this package option is given, all cross-referencing commands
%    will use the \format{vario} format with variable output of the
%    page number, like with \file{varioref.sty}.  This is the default.
%    \begin{macrocode}
\DeclareOption{vario}{%
  \renewcommand*{\fancyrefdefaultformat}{vario}%
}%
%    \end{macrocode}
%    Other local options will be passed to the \package{varioref}
%    package after causing an error message.  If you use e.\,g.\
%    \option{danish} as a \emph{global} option (see
%    \file{clsguide.dvi}), you will get \emph{english}
%    \package{fancyref} strings without a warning or an error, hence
%    be careful.  This is \emph{not} the fault of the
%    \package{fancyref} package, but a feature of the \LaTeXe{} option
%    handler.  You \emph{really} should load the package according to
%    \fref{sec:loading}.
%    \begin{macrocode}
\DeclareOption*{%
  \PackageError{fancyref}{%
    Unknown option ``\CurrentOption''%
  }{%
    The option ``\CurrentOption'' was not declared in
    package ``fancyref'',\MessageBreak
    perhaps you have only misspelled its name.\MessageBreak
    Currently only the languages ``english'' and
    ``german'' are defined.\MessageBreak
    Try typing <return> to proceed.  Most likely your
    output will be wrong,\MessageBreak
    e. g. ``Figure'' instead of ``Abbildung''.%
  }%
  \PassOptionsToPackage{\CurrentOption}{varioref}%
}%
%    \end{macrocode}
%
%
%    \subsubsection{Option Processing}
%
%    If no options are specified, english strings for
%    cross-referencing, loose spacing between string and counter, and
%    variable output of the page numbers will be used by default.
%    Otherwise the options are processed in the order given by the
%    calling command.
%    \begin{macrocode}
\ExecuteOptions{english,loose,vario}%
\ProcessOptions*%
%    \end{macrocode}
%
%
%    \subsubsection{Loading Files}
%
%    This package uses a nice feature of the \package{varioref}
%    package to generate variable output depending on the difference
%    between the page number on which the cross-reference occurs and
%    the page number of the referenced object.  \file{varioref.sty} is
%    therefore required.
%    \begin{macrocode}
\RequirePackage{varioref}%
%    \end{macrocode}
%
%
%    \subsubsection{Defining Commands}
%
%    \begin{macro}{\...labelprefix}
%    Most users distinguish between labels for figures and tables to
%    avoid a mix-up.  This is usually done by prefixing the labels
%    with \prefix{fig} or \prefix{tab}.  These definitions declare the
%    defaults for this classifying part.
%    \begin{macrocode}
\newcommand*{\fancyrefchaplabelprefix}{chap}%
\newcommand*{\fancyrefenumlabelprefix}{enum}%
\newcommand*{\fancyrefeqlabelprefix}{eq}%
\newcommand*{\fancyreffiglabelprefix}{fig}%
\newcommand*{\fancyreffnlabelprefix}{fn}%
\newcommand*{\fancyrefseclabelprefix}{sec}%
\newcommand*{\fancyreftablabelprefix}{tab}%
%    \end{macrocode}
%    \end{macro}
%    To enable user changes of these prefixes it is necessary to do
%    some list processing.\footnote{Credits go to \person{Carsten
%    Heinz} and \person{Heiko Oberdiek} for providing and optimizing
%    this code.  I did not understand a single token in the beginning.
%    \winkey}  There is one command list for each prefix.  It contains
%    a number of macros that will rename the formatting commands
%    defined for this prefix.  Initially, the package defines the
%    \cmd{\@fancyref@ren} command as empty, by means of
%    \cmd{\newcommand*}.  In this way, even with the \cmd{\def} command
%    other macros cannot be overwritten by accident.\footnote{Credits
%    go to \person{Bernd Raichle} for this nice little trick, which is
%    used throughout this package.}
%    \begin{macro}{\@...append@ren}
%    The first argument of the following command is one of those
%    command lists, the second argument is a \package{fancyref}
%    format.  A macro renaming the corresponding formatting command
%    will be appended to the command list.
%    \begin{macrocode}
\newcommand*{\@fancyref@ren}{\@empty}%
\newcommand*{\@fancyref@append@ren}[2]{%
  \ifx\relax#1%
    \def#1{\@fancyref@ren{#2}}%
  \else
    \expandafter\def\expandafter#1%
      \expandafter{#1\@fancyref@ren{#2}}%
  \fi
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@...check@prefix}
%    This command does most of the work, when a prefix is to be
%    renamed.  First, the old, saved prefix for the corresponding
%    object type is recalled.
%    \begin{macrocode}
\newcommand*{\@fancyref@check@prefix}[1]{%
  \expandafter\let\expandafter\@fancyref@old@prefix
    \csname @fancyref@saved@prefix\string#1\endcsname
%    \end{macrocode}
%    The old prefix is compared with the prefix given by the
%    argument.
%    \begin{macrocode}
  \ifx\@fancyref@old@prefix#1%
%    \end{macrocode}
%    If the prefixes are different, the renaming macros are set up.
%    Their only argument will be a \package{fancyref} format.
%    \begin{macrocode}
  \else
    \def\@fancyref@ren##1{%
%    \end{macrocode}
%    The prefixing part of the name will be changed, if the renaming
%    macros are called with the corresponding argument.
%
%    More precisely, the definition of the old formatting command is
%    copied to a new command including the new prefix in its name.
%    \begin{macrocode}
      \expandafter
        \let\csname fr@##1@#1\expandafter\endcsname
          \csname fr@##1@\@fancyref@old@prefix\endcsname
%    \end{macrocode}
%    Then the old command is deleted.
%    \begin{macrocode}
      \expandafter
        \let\csname fr@##1@\@fancyref@old@prefix\endcsname
          \@undefined
    }%
%    \end{macrocode}
%    Now the command list containing the renaming macros for the given
%    prefix is executed.
%    \begin{macrocode}
    \csname @fr@ren@list\string#1\endcsname
%    \end{macrocode}
%    The procedure is repeated for the upper-case formatting
%    commands.
%    \begin{macrocode}
    \def\@fancyref@ren##1{%
      \expandafter
        \let\csname Fr@##1@#1\expandafter\endcsname
          \csname Fr@##1@\@fancyref@old@prefix\endcsname
      \expandafter
        \let\csname Fr@##1@\@fancyref@old@prefix\endcsname
          \@undefined
    }%
    \csname @Fr@ren@list\string#1\endcsname
%    \end{macrocode}
%    Finally the new prefix for the corresponding object type is
%    saved.
%    \begin{macrocode}
    \expandafter\let
      \csname @fancyref@saved@prefix\string#1\endcsname#1%
  \fi
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\...changeprefix}
%    This user command changes the default prefix for an object type
%    (the first argument) to a new string (the second argument).  Then
%    the renaming of the formatting commands is done.
%    \begin{macrocode}
\newcommand*{\fancyrefchangeprefix}[2]{%
  \renewcommand*{#1}{#2}%
  \@fancyref@check@prefix{#1}%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\frefformat}
%    This macro is used to define new formats for the typesetting of
%    cross-references.  It takes three arguments, the first is the
%    name of the declared format, the second is the prefix macro used
%    for this format (e.\,g.\ \cmd{\fancyreffiglabelprefix} for
%    cross-references to figures) and the third describes the output
%    generated by the cross-reference.
%
%    Within the third argument |#1| will be replaced by the counter of
%    the referenced object (i.\,e.\ the output of a \cmd{\ref}
%    command), |#2| will be replaced by the page number (i.\,e.\ the
%    output of a \cmd{\pageref} command) and |#3| will be replaced by
%    the output of a \cmd{\vpageref} command.
%    \begin{macrocode}
\newcommand{\frefformat}[2]{%
%    \end{macrocode}
%    It is checked if the prefix has changed and the already existing
%    formatting commands are renamed.
%    \begin{macrocode}
  \@fancyref@check@prefix{#2}%
%    \end{macrocode}
%    Then the \package{fancyref} format given in the first argument is
%    appended to the command list for the prefix given in the second
%    argument.
%    \begin{macrocode}
  \expandafter\@fancyref@append@ren
    \csname @fr@ren@list\string#2\endcsname{#1}%
%    \end{macrocode}
%    Finally the formatting command is defined.
%    \begin{macrocode}
  \@namedef{fr@#1@#2}##1##2##3%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\Frefformat}
%    The definition of the command for declaring \package{fancyref}
%    formats used at the beginning of a sentence is almost the same,
%    the only difference is that upper-case commands like
%    \cmd{\Fr@sample@ex} are used internally.  This enables usage of
%    \stringdef{figure} within a sentence and \stringdef{Figure} at
%    the beginning of a sentence.
%    \begin{macrocode}
\newcommand{\Frefformat}[2]{%
  \@fancyref@check@prefix{#2}%
  \expandafter\@fancyref@append@ren
    \csname @Fr@ren@list\string#2\endcsname{#1}%
  \@namedef{Fr@#1@#2}##1##2##3%
}%
%    \end{macrocode}
%    \end{macro}
%
%
%    \paragraph{Format Definition.\label{sec:fancyrefformats}}
%
%    Now it is time for the definition of the \package{fancyref}
%    formats.  Generally the \format{vario} formats use the features
%    of the \package{varioref} package, whereas the \format{plain}
%    formats provide the name of the referenced object and its
%    counter, but no page number.
%
%    Of course the various macros for spacing, classifying prefixes
%    and names of the referenced object are used.  This will ensure
%    that the default formats also work after redefining e.\,g.\
%    \cmd{\chaptername} to \stringdef{Fool} and
%    \cmd{\fancyrefchaplabelprefix} to \stringdef{moron}.
%    Cross-references generated by |\fref{moron:bar}| will then come
%    out correctly as \sampleoutput{fool~1}.
%    \begin{macrocode}
\frefformat{vario}{\fancyrefchaplabelprefix}{%
  \frefchapname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyrefchaplabelprefix}{%
  \frefchapname\fancyrefdefaultspacing#1%
}%
\frefformat{vario}{\fancyrefenumlabelprefix}{%
  \frefenumname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyrefenumlabelprefix}{%
  \frefenumname\fancyrefdefaultspacing#1%
}%
%    \end{macrocode}
%    The formats for the cross-refernces to equations are more
%    complex, because I wanted to support the \cmd{\tagform@} command
%    of the \package{amsmath} package \cite{AMS:1996}:
%\begin{verbatim}
%   \makeatletter
%   \renewcommand{\tagform@}[1]{\textup{[#1]}}
%   \makeatother
%\end{verbatim}
%    will make both the equation numbers and the cross-references
%    generated e.\,g.\ by |\fref{eq:bar}| come out as
%    \sampleoutput{[1]}.  Even within a formula a cross-referenced
%    equation number will \emph{not} be typeset in italics.
%    \begin{macrocode}
\@ifundefined{tagform@}{%
  \frefformat{vario}{\fancyrefeqlabelprefix}{%
    \frefeqname\fancyrefdefaultspacing\textup{(#1)}#3%
  }%
  \frefformat{plain}{\fancyrefeqlabelprefix}{%
    \frefeqname\fancyrefdefaultspacing\textup{(#1)}%
  }%
}{%
  \frefformat{vario}{\fancyrefeqlabelprefix}{%
    \frefeqname\fancyrefdefaultspacing
    \textup{\tagform@{#1}}#3%
  }%
  \frefformat{plain}{\fancyrefeqlabelprefix}{%
    \frefeqname\fancyrefdefaultspacing
    \textup{\tagform@{#1}}%
  }%
}%
%    \end{macrocode}
%
%    \label{sec:margin}
%    For figures and tables an additional \package{fancyref} format
%    called \format{margin} is provided to put cross-references into
%    the margin.
%
%    |\mbox{}| will fix an alignment problem, if the \cmd{\marginpar}
%    command occurs prior to the first word of a paragraph, see
%    \cite[p.~75]{Goossens:1994}.  |\hspace{0pt}| enables hyphenation
%    of the very first word of the \cmd{\marginpar} command.
%
%    Marginal notes are typeset in a smaller font and
%    \cmd{\raggedright}.  The \cmd{\rightarrow} is typeset in math
%    mode without the horizontal space usually added by
%    \cmd{\mathsurround}.
%
%    In marginal notes tight spacing is appropriate, because due to
%    the limited space in the margins abbreviated strings are used.
%    \begin{macrocode}
\frefformat{margin}{\fancyreffiglabelprefix}{%
  \mbox{}\marginpar{%
    \raggedright\hspace{0pt}\footnotesize
    \ensuremath{\m@th\rightarrow}~%
    \Freffigshortname\fancyreftightspacing#1,
    \frefpgshortname\fancyreftightspacing#2%
  }%
}%
%    \end{macrocode}
%    The \format{main} format should be used for that cross-reference
%    which explains the referenced object in detail.  Scientific
%    papers usually are browsed very quickly, perhaps the reader stops
%    at a figure or a table and begins to search for the explanation
%    of this float.  Hence it is very helpful to typeset this main
%    cross-reference in bold face and to provide the full information
%    including the page number (with support of the \package{varioref}
%    package).  These \format{main} formats are defined only for
%    floats, i.\,e.\ figures or tables, because for other,
%    non-floating objects the \socalled{main} cross-reference usually
%    can be found very near to the object.
%    \begin{macrocode}
\frefformat{main}{\fancyreffiglabelprefix}{%
  \textbf{\freffigname\fancyrefdefaultspacing#1}#3%
}%
%    \end{macrocode}
%    The rest of the format definitions should now be straight
%    forward.
%    \begin{macrocode}
\frefformat{vario}{\fancyreffiglabelprefix}{%
  \freffigname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyreffiglabelprefix}{%
  \freffigname\fancyrefdefaultspacing#1%
}%
\frefformat{vario}{\fancyreffnlabelprefix}{%
  \freffnname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyreffnlabelprefix}{%
  \freffnname\fancyrefdefaultspacing#1%
}%
\frefformat{vario}{\fancyrefseclabelprefix}{%
  \frefsecname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyrefseclabelprefix}{%
  \frefsecname\fancyrefdefaultspacing#1%
}%
\frefformat{margin}{\fancyreftablabelprefix}{%
  \mbox{}\marginpar{%
    \raggedright\hspace{0pt}\footnotesize
    \ensuremath{\m@th\rightarrow}~%
    \Freftabshortname\fancyreftightspacing#1,
    \frefpgshortname\fancyreftightspacing#2%
  }%
}%
\frefformat{main}{\fancyreftablabelprefix}{%
  \textbf{\freftabname\fancyrefdefaultspacing#1}#3%
}%
\frefformat{vario}{\fancyreftablabelprefix}{%
  \freftabname\fancyrefdefaultspacing#1#3%
}%
\frefformat{plain}{\fancyreftablabelprefix}{%
  \freftabname\fancyrefdefaultspacing#1%
}%
%    \end{macrocode}
%    Now it is time for the upper-case versions of the format
%    definitions.
%    \begin{macrocode}
\Frefformat{vario}{\fancyrefchaplabelprefix}{%
  \Frefchapname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyrefchaplabelprefix}{%
  \Frefchapname\fancyrefdefaultspacing#1%
}%
\Frefformat{vario}{\fancyrefenumlabelprefix}{%
  \Frefenumname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyrefenumlabelprefix}{%
  \Frefenumname\fancyrefdefaultspacing#1%
}%
\@ifundefined{tagform@}{%
  \Frefformat{vario}{\fancyrefeqlabelprefix}{%
    \Frefeqname\fancyrefdefaultspacing\textup{(#1)}#3%
  }%
  \Frefformat{plain}{\fancyrefeqlabelprefix}{%
    \Frefeqname\fancyrefdefaultspacing\textup{(#1)}%
  }%
}{%
  \Frefformat{vario}{\fancyrefeqlabelprefix}{%
    \Frefeqname\fancyrefdefaultspacing
    \textup{\tagform@{#1}}#3%
  }%
  \Frefformat{plain}{\fancyrefeqlabelprefix}{%
    \Frefeqname\fancyrefdefaultspacing
    \textup{\tagform@{#1}}%
  }%
}%
\Frefformat{margin}{\fancyreffiglabelprefix}{%
  \mbox{}\marginpar{%
    \raggedright\hspace{0pt}\footnotesize
    \ensuremath{\m@th\rightarrow}~%
    \Freffigshortname\fancyreftightspacing#1,
    \frefpgshortname\fancyreftightspacing#2%
  }%
}%
\Frefformat{main}{\fancyreffiglabelprefix}{%
  \textbf{\Freffigname\fancyrefdefaultspacing#1}#3%
}%
\Frefformat{vario}{\fancyreffiglabelprefix}{%
  \Freffigname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyreffiglabelprefix}{%
  \Freffigname\fancyrefdefaultspacing#1%
}%
\Frefformat{vario}{\fancyreffnlabelprefix}{%
  \Freffnname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyreffnlabelprefix}{%
  \Freffnname\fancyrefdefaultspacing#1%
}%
\Frefformat{vario}{\fancyrefseclabelprefix}{%
  \Frefsecname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyrefseclabelprefix}{%
  \Frefsecname\fancyrefdefaultspacing#1%
}%
\Frefformat{margin}{\fancyreftablabelprefix}{%
  \mbox{}\marginpar{%
    \raggedright\hspace{0pt}\footnotesize
    \ensuremath{\m@th\rightarrow}~%
    \Freftabshortname\fancyreftightspacing#1,
    \frefpgshortname\fancyreftightspacing#2%
  }%
}%
\Frefformat{main}{\fancyreftablabelprefix}{%
  \textbf{\Freftabname\fancyrefdefaultspacing#1}#3%
}%
\Frefformat{vario}{\fancyreftablabelprefix}{%
  \Freftabname\fancyrefdefaultspacing#1#3%
}%
\Frefformat{plain}{\fancyreftablabelprefix}{%
  \Freftabname\fancyrefdefaultspacing#1%
}%
%    \end{macrocode}
%    \ldots~much tedious work!
%    \begin{macro}{\fancyrefargdelim}
%    \label{sec:delim}
%    The following definition sets up the default for the delimiting
%    character between the \socalled{classifying} part and the
%    \socalled{labeling} part of a label, e.\,g.\ in
%    \labelname{fig:foo} the colon is used as a delimitor.  This can
%    be customized, but most users will stick to the conventional
%    \delimitor{:}.
%    \begin{macrocode}
\newcommand*{\fancyrefargdelim}{:}%
%    \end{macrocode}
%    \end{macro}
%    The following code saves the backslash char in a token register,
%    so it can be used in \cmd{\PackageError}
%    messages.\footnote{Credits go to \person{Bernd Raichle} for this
%    dirty trick.}  Sorry, I do not understand the code due to its
%    \cmd{\catcode} and grouping hacking.  Still much to learn~\ldots
%    \begin{macrocode}
\begingroup \catcode`\|=0 |catcode`|\=12
|toks0={|endgroup
  |def|backslashchar{\}}
|the|toks0 \relax
%    \end{macrocode}
%    \begin{macro}{\@...page@ref}
%    This macro is a hacked version of the \cmd{\vpageref} command
%    from the \package{varioref} package, which removes a space that
%    is superfluous for my purpose.
%    \begin{macrocode}
\newcommand*{\@fancyref@page@ref}{\@ifnextchar[%]
  \@vpageref{\@vpageref[\unskip]}%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@f@ref}
%    This macro now does the real work.  It tests if the specified
%    format for the given classifying prefix exists.  If it does, the
%    formatting command is called with three arguments:  The counter of
%    the referenced object (\cmd{\ref}), the page number of the
%    referenced object (\cmd{\pageref}) and the page number resulting
%    from a \cmd{\vpageref}.  The output of the formatting command
%    will be passed as an argument to the \cmd{\fancyrefhook} command
%    (\frefseename~\frefpgname~\pageref{sec:fancyrefhook}).  If the
%    formatting command does not exist, a package error occurs.
%    \begin{macrocode}
\newcommand*{\@f@ref}[4]{%
  \@ifundefined{#1r@#2@#3}{%
    \PackageError{fancyref}{%
      \backslashchar#1ref\space format ``#2''
      undefined\MessageBreak
      for label type ``#3''%
    }{%
      The format ``#2'' was not defined for the label type
      ``#3''\MessageBreak
      and the \backslashchar#1ref\space command.  Perhaps
      you have only misspelled its name.\MessageBreak
      Otherwise you will have to define it with
      \protect\new#1refformat\MessageBreak
      prior to using it.%
    }%
  }{%
    \fancyrefhook{%
      \@nameuse{#1r@#2@#3}%
        {\ref{#3\fancyrefargdelim#4}}%
        {\pageref{#3\fancyrefargdelim#4}}%
        {\@fancyref@page@ref{#3\fancyrefargdelim#4}}%
    }%
  }%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\fref}
%    This macro is the front-end for the user.  Its first, optional
%    argument is the format of the cross-reference, the second,
%    mandatory argument is the label of the cross-referenced object.
%    If no optional argument is provided, \cmd{\fancyrefdefaultformat}
%    will be used as a format.
%
%    The second argument is then split at the delimiting character
%    (\cmd{\fancyrefargdelim},
%    \frefseename~\frefpgname~\pageref{sec:delim}) into a classifying
%    prefix and the labeling part.  I am sorry that I do not
%    understand the \cmd{\@fref} command completely.  But it works
%    really well,\footnote{Credits go to \person{David Carlisle} who
%    once again send me the cut-and-paste solution for my problems.}
%    and passes four arguments to the \cmd{\@f@ref} command:
%    Lower-case flag, format, classifying prefix and labeling part.
%    \begin{macrocode}
\newcommand*{\@fref}{\@empty}%
\newcommand*{\fref}[2][\fancyrefdefaultformat]{%
  \edef\@fref{%
    \def\noexpand\@fref
      ####1\fancyrefargdelim####2\noexpand\@fref{%
      \noexpand\@f@ref{f}{#1}{####1}{####2}%
    }%
  }%
  \@fref
  \@fref#2\@fref
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\Fref}
%    This macro works exactly the same way as \cmd{\Fref}.  It should
%    be used at the beginning of a sentence and hence passes an
%    upper-case \source{S} to the \cmd{\@f@ref} command.
%    \person{Stefan Ulrich}\footnote{He will easily notice that his
%    name was typeset without his additions to the \package{soul}
%    package \cite{Franz:1998}.  \winkey} told  me kindly that it is
%    very difficult to implement a reliable heuristic to check for the
%    start of a sentence.  So I decided to leave this as an exercise
%    for the reader.  \winkey
%    \begin{macrocode}
\newcommand*{\@Fref}{\@empty}%
\newcommand*{\Fref}[2][\fancyrefdefaultformat]{%
  \edef\@Fref{%
    \def\noexpand\@Fref
      ####1\fancyrefargdelim####2\noexpand\@Fref{%
      \noexpand\@f@ref{F}{#1}{####1}{####2}%
    }%
  }%
  \@Fref
  \@Fref#2\@Fref
}%
%</package>
%    \end{macrocode}
%    \end{macro}
%    \Finale
%    \iffalse
%<*testfile>
\documentclass[12pt,a4paper]{ltxdoc}
%
\usepackage{fancyref}
\fancyrefaddcaptions{english}{%
  \newcommand*{\Frefthmname}{Theorem}%
  \newcommand*{\frefthmname}{\MakeLowercase{\Frefthmname}}%
}%
%
\newcommand*{\booktitle}[1]{``#1''}
\newcommand*{\format}[1]{\texttt{#1}}
\newcommand*{\labelname}[1]{\texttt{#1}}
\newcommand*{\option}[1]{\texttt{#1}}
\newcommand*{\package}[1]{\texttt{#1}}
\newcommand*{\person}[1]{\textsc{#1}}
\newcommand*{\prefix}[1]{\texttt{#1}}
\newcommand*{\stringdef}[1]{``#1''}
%
\newtheorem{theorem}{Theorem}
%
\begin{document}
%
Let us start with a famous equation:
\begin{equation}
  \label{eq:pythagoras}
  a^2 + b^2 = c^2
\end{equation}
\Fref{eq:pythagoras} has been proven by \person{Pythagoras}.  And this
cross-reference was made with |\Fref{eq:pythagoras}|.  Note that I
really wrote:
\begin{verbatim}
   \Fref{eq:pythagoras} has ...
\end{verbatim}
I did not use:
\begin{verbatim}
   Equation~(\Fref{eq:pythagoras}) has ...
\end{verbatim}

See the next page for further features of the \package{fancyref}
package, I need this page break for demonstration purposes.

\clearpage
The cross-reference works also in the middle of a sentence:
\person{Pythagoras} has proven \fref{eq:pythagoras}.  And this
cross-reference was made with |\fref{eq:pythagoras}|.  You can see the
fancy output from the \package{varioref} package.

Oh, you do not like this package and want normal \cmd{\ref} output
instead?  No problem, just redefine the default format:
\renewcommand*{\fancyrefdefaultformat}{plain}
\begin{verbatim}
   \renewcommand*{\fancyrefdefaultformat}{plain}
\end{verbatim}
Now the cross-reference looks like this:  \Fref{eq:pythagoras}.  There
is also a package option called \option{plain} for this purpose.

Oh, you do not like \stringdef{Equation} and want \stringdef{Eq.}
instead?  No problem, just redefine the string:
\renewcommand*{\Frefeqname}{Eq.}
\begin{verbatim}
   \renewcommand*{\Frefeqname}{Eq.}
\end{verbatim}
\Fref{eq:pythagoras} and \fref{eq:pythagoras} will be the result,
respectively.  Note that there is no need to redefine
\cmd{\frefeqname} to \stringdef{eq.}.  The \package{fancyref} package
will do this automatically for you.  But of course you can use
\stringdef{eqn.} instead, if you really want to.

Oh, you are not using the colon as a delimitor but rather the dash?  No
problem, just redefine the character:
\renewcommand*{\fancyrefargdelim}{-}
\begin{verbatim}
   \renewcommand*{\fancyrefargdelim}{-}
\end{verbatim}
The new test equation with label \labelname{eq-trivial} will be:
\begin{equation}
  \label{eq-trivial}
  a = a
\end{equation}
The cross-reference |\fref{eq-trivial}| will give \fref{eq-trivial} as
output, as expected.

All that stuff may be nice, but you are using \prefix{eqn} instead of
\prefix{eq}?  No problem, just redefine the prefix:
\fancyrefchangeprefix{\fancyrefeqlabelprefix}{eqn}
\begin{verbatim}
   \fancyrefchangeprefix{\fancyrefeqlabelprefix}{eqn}
\end{verbatim}
We need a new, fantastic test equation with label
\labelname{eqn-fantastic}:
\begin{equation}
  \label{eqn-fantastic}
  b = b
\end{equation}
The cross-reference |\fref{eqn-fantastic}| will give
\fref{eqn-fantastic} as output, as expected.

Maybe the spacing between \stringdef{eq.} and ``3'' is too generous,
let us tighten things a bit, with
\renewcommand*{\fancyrefdefaultspacing}{\fancyreftightspacing}
\begin{verbatim}
   \renewcommand*{\fancyrefdefaultspacing}{%
     \fancyreftightspacing
   }
\end{verbatim}
the spacing looks like \fref{eqn-fantastic}.  If you think this is
better, just use the \option{tight} option of this package.
\fancyrefchangeprefix{\fancyrefeqlabelprefix}{eq}

Perhaps you want parentheses around the cross-reference?  No problem,
just redefine the appropriate hook:
\renewcommand*{\fancyrefhook}[1]{(#1)}
\begin{verbatim}
   \renewcommand*{\fancyrefhook}[1]{(#1)}
\end{verbatim}
The result from |\fref{eq-trivial}| is \fref{eq-trivial}.  In fact
this could have been obtained easier, as I provided an package option
just for this purpose:
\begin{verbatim}
   \usepackage[paren]{fancyref}
\end{verbatim}

Now let us try something really cool.  What about introducing a new
type of objects, e.\,g.\ theorems, with \prefix{thm} prefixed, new
strings like \stringdef{Theorem} added and the cross-reference in huge
italics?  Also, as you have read in that bargain textbook on
typography (\booktitle{cAN U rEaD It} by \person{John Badmountain}),
cross-references to theorems should be typeset as footnotes.  No
problem:  First, we need a new prefix:
\newcommand*{\fancyrefthmlabelprefix}{thm}
\begin{verbatim}
   \newcommand*{\fancyrefthmlabelprefix}{thm}
\end{verbatim}
Then we declare a new \package{fancyref} format called \format{foot}:
\frefformat{foot}{\fancyrefthmlabelprefix}{%
  \unskip\footnote{%
    \huge\itshape\Frefthmname\fancyrefdefaultspacing#1#3%
  }%
}
\Frefformat{foot}{\fancyrefthmlabelprefix}{%
  \unskip\footnote{%
    \huge\itshape\Frefthmname\fancyrefdefaultspacing#1#3%
  }%
}
\begin{verbatim}
   \frefformat{foot}{\fancyrefthmlabelprefix}{%
     \unskip\footnote{%
       \huge\itshape\Frefthmname\fancyrefdefaultspacing#1#3%
     }%
   }
   \Frefformat{foot}{\fancyrefthmlabelprefix}{%
     \unskip\footnote{%
       \huge\itshape\Frefthmname\fancyrefdefaultspacing#1#3%
     }%
   }
\end{verbatim}
The strings have to be setup in the preamble of the document, I did
this already, because I knew it would be necessary.  The code I used
was:
\begin{verbatim}
   \fancyrefaddcaptions{english}{%
     \newcommand*{\Frefthmname}{Theorem}%
     \newcommand*{\frefthmname}{%
       \MakeLowercase{\Frefthmname}%
     }%
   }%
\end{verbatim}
And finally this is the test theorem:
\begin{theorem}[Murphy]
  \label{thm-murphy}
  If something \emph{can} go wrong, it \emph{will} go wrong.
\end{theorem}
Now let us try it.  |\Fref[foot]{thm-murphy}| comes out
as \Fref[foot]{thm-murphy}.  Oops, the hook is still at work, I will
just reset it to its default value:
\renewcommand*{\fancyrefhook}[1]{#1}%
\begin{verbatim}
   \renewcommand*{\fancyrefhook}[1]{#1}
\end{verbatim}
And now?  \Fref[foot]{thm-murphy} Gotcha!
%
\end{document}
%</testfile>
%    \fi
\endinput