summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/hyperref/backref.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:54:03 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:54:03 +0000
commit6dc1c9960a84a72228cacdea73160739d0d7243a (patch)
tree78de0243faedc6a10a36731ca9bf341c94e391e6 /Master/texmf-dist/source/latex/hyperref/backref.dtx
parente71364f18cbfb00305b86b52f2d0bb5f0d338f7e (diff)
trunk/Master/texmf-dist/source/latex/hyperref
git-svn-id: svn://tug.org/texlive/trunk@327 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/hyperref/backref.dtx')
-rw-r--r--Master/texmf-dist/source/latex/hyperref/backref.dtx595
1 files changed, 595 insertions, 0 deletions
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