From 6dc1c9960a84a72228cacdea73160739d0d7243a Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 11 Jan 2006 23:54:03 +0000
Subject: trunk/Master/texmf-dist/source/latex/hyperref

git-svn-id: svn://tug.org/texlive/trunk@327 c570f23f-e606-0410-a88d-b1316a301751
---
 .../texmf-dist/source/latex/hyperref/backref.dtx   | 595 +++++++++++++++++++++
 1 file changed, 595 insertions(+)
 create mode 100644 Master/texmf-dist/source/latex/hyperref/backref.dtx

(limited to 'Master/texmf-dist/source/latex/hyperref/backref.dtx')

diff --git a/Master/texmf-dist/source/latex/hyperref/backref.dtx b/Master/texmf-dist/source/latex/hyperref/backref.dtx
new file mode 100644
index 00000000000..5a25459c36e
--- /dev/null
+++ b/Master/texmf-dist/source/latex/hyperref/backref.dtx
@@ -0,0 +1,595 @@
+\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
-- 
cgit v1.2.3

