\def\fileversion{1.23}
\def\filedate{2003/03/20}
%
% \iffalse
%% File: backref.dtx Copyright (C) 1995-2003 David Carlisle, Sebastian Rahtz, Heiko Oberdiek
%
%% This file is part of the `Hyperref Bundle'.
%% -------------------------------------------
%%
%% It may be distributed under the conditions of the LaTeX Project Public
%% License, either version 1.2 of this license or (at your option) any
%% later version.  The latest version of this license is in
%%    http://www.latex-project.org/lppl.txt
%% and version 1.2 or later is part of all distributions of LaTeX
%% version 1999/12/01 or later.
%%
%% The list of all files belonging to the `Hyperref Bundle' is
%% given in the file `manifest.txt'.
%<*driver>
\documentclass{ltxdoc}
\begin{document}
  \title{%
    Back referencing from bibliographical citations%
    \thanks{%
      This file has version number \fileversion,
      last revised \filedate.%
    }%
  }
  \author{David Carlisle and Sebastian Rahtz}
  \date{\filedate}
  \maketitle
  \tableofcontents
  \DocInput{backref.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{505}
% \MakeShortVerb{|}
% \section{Introduction}
%
% \section{Usage}
%
% \subsection{Options}
%
% \subsubsection{Options for type of back references}
%
%    In short the following options set the type of back
%    references. Default is option |pageref|.
%    \begin{quote}
%    \begin{tabular}{@{}ll@{}}
%      |ref| & section number\\
%      |pageref| & page number\\
%      |hyperref| & section number as hyper link\\
%      |hyperpageref| & page number as hyper link
%    \end{tabular}
%    \end{quote}
%    The options that start with |hyper| are intended for
%    the use with package |hyperref|. In this case package
%    |backref| will be loaded automatically if the |hyperref|
%    options |backref| or |pagebackref| are given. Package
%    |hyperref| then loads package |backref| with the appropriate
%    option:
%    \begin{quote}
%    \begin{tabular}{@{}ll@{}}
%      |hyperref| option & |backref| option set by |hyperref|\\
%      \hline
%      |backref|         & |hyperref|\\
%      |backref=section| & |hyperref|\\
%      |backref=slide|   & |hyperref|\\
%      |backref=page|    & |hyperpageref|\\
%      |pagebackref|     & |hyperpageref|
%    \end{tabular}
%    \end{quote}
%
% \subsubsection{Language options}
%
%    Currently supported are options |english| (default), |UKenglish|,
%    |USenglish|, |british|, |german|, |ngerman|, |austrian|, |naustrian|,
%    |french|, |francais|, and |spanish|.
%
% \subsection{Formatting of the back references list}
%
%    Package |backref| has to be able to detect the end of an entry
%    in the bibliography, therefore each \cmd{\bibitem} entry must
%    be ended by an empty line (or a |\par| token).
%
%    Example:
%\begin{quote}
%\begin{verbatim}
%\begin{thebibliography}{9}
%\bibitem[bib:abc] First entry.
%
%\bibitem[bib:foo] Second entry.
%
%\end{thebibliography}
%\end{verbatim}
%\end{quote}
%
%    Then package |backref| can add hooks for the back references list.
%    at the end of the entry. The list is separated by \cmd{\newblock},
%    if the used bibliography package supports this. The package options
%    control the kind of back references (page numbers, sections numbers),
%    whereas the hooks control the formatting.
%
%    There are two hooks \cmd{\backref} and a new hook \cmd{\backrefalt},
%    available since version 1.21 of package |backref|. The former one
%    is enabled by default.
%
% \subsubsection{Formatting hook \cmd{\backref}}
%
%    Macro \cmd{\backref} has a a comma separated
%    list of backref references as first and only argument.
%    With hyperref options only this list will be printed. Without
%    hyperref there is an introductionary text, controlled by
%    macros \cmd{\backrefpagesname} or \cmd{\backrefsectionsname}.
%
% \subsubsection{Formatting hook \cmd{\backrefalt}}
%
%    \cmd{\backrefalt} is a new interface since version 1.21 of package
%    |backref|. It takes four arguments:
%    \begin{enumerate}
%    \item Number of citations without dupes.
%    \item Back references list without dupes.
%    \item Number of all citations (with dupes).
%    \item Back reference list with all entries (with dupes).
%    \end{enumerate}
%    The latter options consider equal entries as one entry.
%    Now \cmd{\backrefalt} can easily be defined with text that
%    depends on the number of citations, for example:
%\begin{quote}
%\begin{verbatim}
%\usepackage[backref]{backref}
%\renewcommand*{\backref}[1]{}
%\renewcommand*{\backrefalt}[4]{%
%  \ifcase #1 %
%    No citations.%
%  \or
%    One citation in section #2.%
%  \else
%    #1 citations in sections #2.%
%  \fi
%}
%\end{verbatim}
%\end{quote}
%    The separation between the list entries are controlled by
%    the following macros:
%    \begin{itemize}
%    \item \cmd{\backrefsep}: inserted between entries except for the
%      next cases, default is ``\verb*|, |''.
%    \item \cmd{\backreftwosep}: inserted between entries in
%      a list of two entries, default is ``\verb*| and~|''.
%    \item \cmd{\backreflastsep}: inserted between the last two
%      entries of a list with more than two entries, default is
%      ``\verb*|, and~|''.
%    \end{itemize}
%    Examples:
%    \begin{quote}
%    \meta{entry1}\\
%    \meta{entry1} \cmd{\backreftwosep} \meta{entry2}\\
%    \meta{entry1} \cmd{\backrefsep} \meta{entry2}
%      \cmd{\backreflastsep} \meta{entry3}
%    \end{quote}
%
% \StopEventually{}
%
% \section{The macros}
%    Internal command names of this package start with |\BR@|,
%    commands, that store the original meaning of commands, which
%    will be redefined, are prefixed with |\BRorg@|.
%
% \subsection{Package identification}
%    \begin{macrocode}
%<*package>
\ProvidesPackage{backref}%
  [\filedate\space v\fileversion\space Bibliographical back referencing]
%    \end{macrocode}
%
% \subsection{Options}
%
% \subsubsection{Option verbose}
%    If package hyperref is loaded, then its setting is used as
%    default for the verbose switch.
%    \begin{macrocode}
\newif\ifBR@verbose
\@ifundefined{ifHy@verbose}{%
  \BR@verbosefalse
}{%
  \let\ifBR@verbose\ifHy@verbose
}
\DeclareOption{verbose}{\BR@verbosetrue}
%    \end{macrocode}
%
% \subsubsection{Options for way of working}
%
%    What is printed depends on how the 3 available items of
%    information are used (page number, section number, label).
%    \begin{macrocode}
\long\def\page@backref#1#2#3{#1}
\long\def\section@backref#1#2#3{#2}
\long\def\hyper@section@backref#1#2#3{\hyperlink{#3}{#2}}
\long\def\hyper@page@backref#1#2#3{\hyperlink{page.#1}{#1}}
%    \end{macrocode}
%    Now the options follows, that can be used without
%    package hyperref.
%    \begin{macrocode}
\DeclareOption{pageref}{%
  \def\backref{\backrefpagesname\ }%
  \let\backrefxxx\page@backref
}
\DeclareOption{ref}{%
  \def\backref{\backrefsectionsname\ }%
  \let\backrefxxx\section@backref
}
%    \end{macrocode}
%    Set up back-referencing to be hyper links, by page or section.
%    \begin{macrocode}
\DeclareOption{hyperref}{%
  \def\backref{}\let\backrefxxx\hyper@section@backref
}
\DeclareOption{hyperpageref}{%
  \def\backref{}\let\backrefxxx\hyper@page@backref
}
%    \end{macrocode}
%
% \subsubsection{Language options}
%
%    \begin{macrocode}
\def\backrefenglish{%
  \def\backrefpagesname{pages}%
  \def\backrefsectionsname{sections}%
  \def\backrefsep{, }%
  \def\backreftwosep{ and~}%
  \def\backreflastsep{, and~}%
}
\def\backrefgerman{%
  \def\backrefpagesname{Seiten}%
  \def\backrefsectionsname{Abschnitte}%
  \def\backrefsep{, }%
  \def\backreftwosep{ und~}%
  \def\backreflastsep{ und~}%
}
\def\backreffrench{%
  \def\backrefpagesname{pages}%
  \def\backrefsectionsname{sections}%
  \def\backrefsep{, }%
  \def\backreftwosep{ et~}%
  \def\backreflastsep{ et~}%
}
\def\backrefspanish{%
  \def\backrefpagesname{p\'aginas}
  \def\backrefsectionsname{secciones}
  \def\backrefsep{, }%
  \def\backreftwosep{ y~}%
  \def\backreflastsep{ y~}%
}
\def\backrefafrikaans{%
  \def\backrefpagesname{bladsye}%
  \def\backrefsectionsname{afdelings}%
  \def\backrefsep{, }%
  \def\backreftwosep{ en~}%
  \def\backreflastsep{ en~}%
}%
%    \end{macrocode}
%    Instead of package babel's definition of \cmd{\addto} the
%    implementation of package varioref is used. Additionally
%    argument |#1| is checked for \cmd{\relax}.
%    \begin{macrocode}
\def\BR@addto#1#2{%
  #2%
  \@temptokena{#2}%
  \ifx#1\relax
    \let#1\@empty
  \fi
  \ifx#1\undefined
     \edef#1{\the\@temptokena}%
  \else
     \toks@\expandafter{#1}%
     \edef#1{\the\toks@\the\@temptokena}%
  \fi
  \@temptokena{}\toks@\@temptokena
}
%    \end{macrocode}
%    \begin{macrocode}
\def\BR@DeclareLang#1#2{%
  \begingroup
    \edef\x##1##2{%
      \noexpand\ifx##2\relax
        \errmessage{No definitions for language `#2' found!}%
      \noexpand\fi
      \endgroup
      \noexpand\DeclareOption{#1}{%
        \noexpand\BR@addto{\noexpand##1}{\noexpand##2}%
      }%
    }%
  \expandafter\x\csname extras#1\expandafter\endcsname
                \csname backref#2\expandafter\endcsname
}
\BR@DeclareLang{english}{english}
\BR@DeclareLang{UKenglish}{english}
\BR@DeclareLang{USenglish}{english}
\BR@DeclareLang{british}{english}
\BR@DeclareLang{german}{german}
\BR@DeclareLang{ngerman}{german}
\BR@DeclareLang{austrian}{german}
\BR@DeclareLang{naustrian}{german}
\BR@DeclareLang{french}{french}
\BR@DeclareLang{frenchb}{french}
\BR@DeclareLang{francais}{french}
\BR@DeclareLang{spanish}{spanish}
\BR@DeclareLang{afrikaans}{afrikaans}
%    \end{macrocode}
%    Default is the english version:
%    \begin{macrocode}
\backrefenglish
%    \end{macrocode}
%
% \subsubsection{Process options}
%
%    \begin{macrocode}
\ExecuteOptions{pageref}
\ProcessOptions*\relax
%    \end{macrocode}
%
% \subsection{The bibliography}
%
%    \begin{macro}{\BR@bibitem}
%    \begin{macrocode}
\def\BR@bibitem{\@ifnextchar[\BR@@lbibitem\BR@@bibitem}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
\def\BR@@lbibitem[#1]#2#3\par{%
  \BRorg@bibitem[#1]{#2}#3%
  \BR@backref{#2}%
}%
\def\BR@@bibitem#1#2\par{%
  \BRorg@bibitem{#1}#2%
  \BR@backref{#1}%
}
\def\BR@backref#1{%
  \newblock
  \begingroup
    \csname @safe@activestrue\endcsname
    \expandafter\providecommand\csname brc@#1\endcsname{0}%
    \expandafter\providecommand\csname brcd@#1\endcsname{0}%
    \csname @safe@activesfalse\expandafter\endcsname
    \expandafter\backref\csname br@#1\expandafter\endcsname
    \expandafter\backrefalt\csname brc@#1\expandafter\endcsname
                         \csname brl@#1\expandafter\endcsname
                         \csname brcd@#1\expandafter\endcsname
                         \csname brld@#1\endcsname
  \endgroup
  \par
}
\@ifundefined{newblock}{\def\newblock{\par}}{}
\providecommand*{\backrefalt}[4]{}
%    \end{macrocode}
%
% \subsection{Reading .brf file}
%
%    \begin{macro}{\backcite}
%    The file |\jobname.brf| collects the back cite informations
%    as calls of \cmd{\backcite} with the informations
%    in the arguments.
%
%    The first argument of macro \cmd{\backcite} is the citation
%    label, the second parameter contains the page number
%    (\cmd{\thepage}), the current label of the citation
%    (\cmd{\@currentlabel}), and the current anchor name
%    (\cmd{\@currentHref}). Example for a citation at the
%    first page in second section:
%\begin{verbatim}
%\backcite {bib:abc}{{1}{2}{section.2}}
%\end{verbatim}
%
%    While the file |\jobname.brf| is read, the informations are
%    collected and stored in macros whose names are build by the
%    citation label \meta{label}:
%    \begin{quote}
%    \begin{tabular}{@{}ll@{}}
%      |\br@|\meta{label} & list, entries separated by comma without dupes\\
%      |\brc@|\meta{label} & number of citations without dupes\\
%      |\brl@|\meta{label} & backref list without dupes\\
%      |\brcd@|\meta{label} & number of all citations (with dupes)\\
%      |\brld@|\meta{label} & backref list with all entries (with dupes)
%    \end{tabular}
%    \end{quote}
%    What are ``dupes''? An instance: you have three references to
%    an entry in the bibliography on the first page:
%\begin{verbatim}
%\backcite {bib:abc}{{1}{1}{section.1}}
%\backcite {bib:abc}{{1}{1}{section.1}}
%\backcite {bib:abc}{{1}{2}{section.2}}
%\end{verbatim}
%    Then the whole backref list with option |pageref| would print, e.g.:
%    \begin{quote}
%    Entry for |bib:abc|. Cited on pages 1, 1, 1.
%    \end{quote}
%    Without dupes the entries with the same page number would be removed,
%    e.g.:
%    \begin{quote}
%    Entry for |bib:abc|. Cited on page 1.
%    \end{quote}
%    Also the third entry is removed, because it has the same page number.
%    For the comparison only these pieces of information are considered
%    that will be used later by \cmd{\backrefxxx}. With option
%    |pageref| macro \cmd{\backrefxxx} becomes \cmd{\page@backref} that
%    throws away the second and third argument and only uses the first
%    argument with the page number. To be more precise, the first
%    expansion of \cmd{\backrefxxx} is used in comparison. If some
%    arguments are used here, but later omitted, then this will not
%    be detected.
%
%    \begin{macro}{\backrefxxxdupe}
%    With option |hyperref| you will get two entries
%    in the following example because the second entry differs in the
%    link information, so the result will be the same section number,
%    but as different links.
%\begin{verbatim}
%\backref {bib:abc}{{1}{1}{section.1}}
%\backref {bib:abc}{{1}{1}{equation.1}}
%\end{verbatim}
%    Macro \cmd{\backrefxxxdupe} will be used
%    in the comparison test if it is defined. Thus you can provide a
%    definition in this case as follows:
%\begin{verbatim}
%\newcommand*{\backrefxxxdupe}[3]{#2}
%\end{verbatim}
%    Then only the section number is interpreted, but not the anchor name.
%    \end{macro}
%
%    To avoid same entries, it is checked before, whether the entry
%    already exists. Only the information needed by \cmd{\backrefxxx}
%    is compared.
%    \begin{macrocode}
\def\backcite#1#2{%
  \@for\x:=#1\do{%
    \begingroup
      \csname @safe@activestrue\endcsname
      \edef\x{\endgroup
        \def\noexpand\x{\expandafter\@firstofone\x\@empty}%
      }%
    \x
%    \end{macrocode}
%    Now macro \cmd{\x} contains the citation label name.
%    \begin{macrocode}
    \expandafter\ifx\csname br@\x\endcsname\relax
%    \end{macrocode}
%    Initialization, fill in the first entry.
%    \begin{macrocode}
      \expandafter\protected@xdef\csname br@\x\endcsname{%
        \protect\backrefxxx#2%
      }%
      \global\expandafter\let\csname brl@\x\expandafter\endcsname
                      \csname br@\x\endcsname
      \global\expandafter\let\csname brld@\x\expandafter\endcsname
                      \csname br@\x\endcsname
      \expandafter\gdef\csname brc@\x\endcsname{1}%
      \expandafter\gdef\csname brcd@\x\endcsname{1}%
    \else
%    \end{macrocode}
%    Fill in further entry. But check for dupe first.
%    \begin{macrocode}
      \begingroup
        \@ifundefined{backrefxxxdupe}{}{\let\backrefxxx\backrefxxxdupe}%
        \expandafter\def\expandafter\reserved@a\expandafter{%
          \backrefxxx#2%
        }%
        \let\BRorg@backrefxxx\backrefxxx
        \global\let\BR@found=N%
        \long\def\backrefxxx##1##2##3{%
          \expandafter\def\expandafter\reserved@b\expandafter{%
            \BRorg@backrefxxx{##1}{##2}{##3}%
          }%
          \ifx\reserved@a\reserved@b
            \global\let\BR@found=Y%
          \fi
        }%
        \setbox\@tempboxa\hbox{\csname br@\x\endcsname}%
      \endgroup
      \let\backrefsep\relax
      \def\backreftwosep{\backrefsep}%
      \def\backreflastsep{\backrefsep}%
      \if N\BR@found
        \expandafter\protected@xdef\csname br@\x\endcsname{%
          \csname br@\x\endcsname, %
          \protect\backrefxxx#2%
        }%
        \expandafter\protected@xdef\csname brl@\x\endcsname{%
          \csname brl@\x\endcsname
          \ifnum\@nameuse{brc@\x}=1 %
            \noexpand\backreftwosep
          \else
            \noexpand\backreflastsep
          \fi
          \protect\backrefxxx#2%
        }%
        \count@=\@nameuse{brc@\x}\relax
        \advance\count@ by 1 %
        \expandafter\xdef\csname brc@\x\endcsname{\the\count@}%
      \fi
      \expandafter\protected@xdef\csname brld@\x\endcsname{%
        \csname brld@\x\endcsname
        \ifnum\@nameuse{brcd@\x}=1 %
          \noexpand\backreftwosep
        \else
          \noexpand\backreflastsep
        \fi
        \protect\backrefxxx#2%
      }%
      \count@=\@nameuse{brcd@\x}\relax
      \advance\count@ by 1 %
      \expandafter\xdef\csname brcd@\x\endcsname{\the\count@}%
    \fi
  }%
}
%    \end{macrocode}
%    \end{macro}
%
% \subsection{Initialization}
%
%    \begin{macrocode}
\def\@currentHref{}
\AtBeginDocument{%
  \let\BRorg@bibitem\bibitem
  \let\bibitem\BR@bibitem
  \let\BRorg@thebibliography\thebibliography
  \def\thebibliography{%
    \@starttoc{brf}{}%
    \BRorg@thebibliography
  }%
  \@ifundefined{NAT@parse}{%
    \global\let\BRorg@citex\@citex
    \global\let\@citex\BR@citex
  }{%
    \@ifpackageloaded{hyperref}{}{%
      \def\hyper@natlinkstart#1{\Hy@backout{#1}}%
    }%
    \PackageInfo{backref}{** backref set up for natbib **}%
  }%
}
%    \end{macrocode}
%
% \subsection{Collecting back cite informations}
%
%    \begin{macro}{\BR@citex}
%    \begin{macrocode}
\def\BR@citex[#1]#2{%
  \BRorg@citex[#1]{#2}%
  \ifBR@verbose
    \PackageInfo{backref}{back cite \string`#2\string'}%
  \fi
  \Hy@backout{#2}%
}
%    \end{macrocode}
%    \end{macro}
%
% Grr. for chicago.sty
%    \begin{macrocode}
\@ifpackageloaded{chicago}{%
  \let\BRorg@citedatax\@citedatax
  \def\@citedatax[#1]#2{%
    \BRorg@citedatax[#1]{#2}%
    \Hy@backout{#2}%
  }%
}{}
%    \end{macrocode}
%    \begin{macro}{\Hy@backout}
%    \begin{macrocode}
\def\Hy@backout#1{%
  \@bsphack
  \ifx\@empty\@currentlabel
    \protected@write\@auxout{}{%
      \string\@writefile{brf}{%
        \string\backcite{#1}{{\thepage}{(document)}{Doc-Start}}%
      }%
    }%
  \else
   \protected@write\@auxout{}{%
     \string\@writefile{brf}{%
       \string\backcite{#1}{{\thepage}{\@currentlabel}{\@currentHref}}%
     }%
   }%
  \fi
  \@esphack
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
\endinput