From 6dc1c9960a84a72228cacdea73160739d0d7243a Mon Sep 17 00:00:00 2001 From: Karl Berry 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} +% +% \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} +% +% \end{macrocode} +% +% \Finale +% +\endinput -- cgit v1.2.3