% \iffalse %% File: backref.dtx Copyright (C) 1995-2009 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'. % %<*dtx> \ProvidesFile{backref.dtx} % %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{backref} %\ProvidesFile{backref.drv} % \fi % \ProvidesFile{backref.dtx} [2009/11/14 v1.29 Bibliographical back referencing]% % % \CheckSum{620} % % \iffalse %<*driver> \documentclass{ltxdoc} \usepackage[numbered]{hypdoc} \usepackage{bmhydoc} \usepackage{backref} \EnableCrossrefs \CodelineIndex \begin{document} \GetFileInfo{backref.sty}% \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 \makeatletter \@ifundefined{HyperrefOverview}{}{% \HyperrefOverview*% }% \tableofcontents \DocInput{backref.dtx}% \PrintIndex \end{document} % % \fi % % \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{Detecting the end of a bibliography entry} % % 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). % \nopagebreak % % 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 automatically add hooks % for the back references list at the end of the entries. % % \DescribeMacro{\backrefparscanfalse} % \DescribeMacro{\backrefparscantrue} % Sometimes it is not appropriate if the entry is read as % argument. For example, catcode changes for verbatim stuff % do not have the desired effect. Therefore the scan for % the \cs{par} token can be disabled by \cs{backrefparscanfalse} % before \cs{bibitem} and enabled by \cs{backrefparscantrue} % afterwards. % % \DescribeMacro{\backrefprint} % If the scan for the end of the entry is disabled, then package % |backref| does not know where to put the back references % list. The list is printed by the macro \cs{backrefprint}, thus % just call it at the right place. Example: %\begin{quote} %\begin{verbatim} %\backrefparscanfalse % disable scan for entry ending %\bibitem[...]{...} % ... \verb|...| ... % potentially dangerous stuff % ... \url{...} ... % \backrefprint % print back reference list here %\backrefparscantrue % enable scan again %\end{verbatim} %\end{quote} % % \subsection{Formatting of the back references list} % % The back references list is separated from the entry % 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 \cs{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 \cs{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> % \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}{\ifbackrefparscan} % \begin{macrocode} \newif\ifbackrefparscan \backrefparscantrue % \end{macrocode} % \end{macro} % % \begin{macro}{\BR@bibitem} % \begin{macrocode} \def\BR@bibitem{% \ifbackrefparscan \expandafter\@ifnextchar\expandafter[\expandafter \BR@@lbibitem\expandafter\BR@@bibitem \else \expandafter\@ifnextchar\expandafter[\expandafter \BR@@@lbibitem\expandafter\BR@@@bibitem \fi } % \end{macrocode} % \end{macro} % \begin{macrocode} \def\BR@@lbibitem[#1]#2#3\par{% \let\backrefprint\BR@backrefprint \BRorg@bibitem[{#1}]{#2}#3% \BR@backref{#2}% }% \def\BR@@bibitem#1#2\par{% \let\backrefprint\BR@backrefprint \BRorg@bibitem{#1}#2% \BR@backref{#1}% } \def\BR@@@lbibitem[#1]#2{% \def\backrefprint{\BR@backref{#2}}% \BRorg@bibitem[{#1}]{#2}% } \def\BR@@@bibitem#1{% \def\backrefprint{\BR@backref{#1}}% \BRorg@bibitem{#1}% } \def\BR@backrefprint{% \PackageError{backref}{% \string\backrefprint\space is only available after \string\bibitem \MessageBreak with setting \string\backrefparscanfalse }\@ehc } \let\backrefprint\BR@backrefprint \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{% \BR@starttoc \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} % \begin{macro}{\BR@starttoc} % \begin{macrocode} \def\BR@starttoc{% \begingroup \makeatletter \@input{\jobname.brf}% \if@filesw \@ifundefined{tf@brf}{% \expandafter\newwrite\csname tf@brf\endcsname }{}% \@ifundefined{tf@brf@open}{% \immediate\openout\csname tf@brf\endcsname\jobname.brf\relax \gdef\tf@brf@open{}% }{}% \fi \@nobreakfalse \endgroup } % \end{macrocode} % \end{macro} % % \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} % % \subsection{Rerun warning} % % The following code computes a MD5 sum and the file size of the % |.brf| file at the begin and the end of the document and compares % them. A rerun warning is given, if they do not match. % This method requires pdf\TeX\ or Lua\TeX. The method fails, % if the MD5 sum and the file size are the same for % a changed |.brf| file (it's probably very seldom). % \begin{macrocode} \RequirePackage{pdftexcmds}[2009/04/10] \begingroup \xdef\BR@CheckSumBefore{% \@ifundefined{pdf@filemdfivesum}{}{% \pdf@filemdfivesum{\jobname.brf}% }% :% \@ifundefined{pdf@filesize}{}{% \pdf@filesize{\jobname.brf}% }% }% \endgroup \AtBeginDocument{% \AtEndDocument{% \clearpage \if@filesw \immediate\write\@mainaux{% \string\csname\space BR@CheckEnd\string\endcsname }% \fi }% % \end{macrocode} % \begin{macro}{\BR@CheckEnd} % \begin{macrocode} \def\BR@CheckEnd{% \begingroup \@ifundefined{tf@brf@open}{}{% \immediate\closeout\tf@brf }% \edef\BR@CheckSumAfter{% \@ifundefined{pdf@filemdfivesum}{}{% \pdf@filemdfivesum{\jobname.brf}% }% :% \@ifundefined{pdf@filesize}{}{% \pdf@filesize{\jobname.brf}% }% }% \ifx\BR@CheckSumBefore\BR@CheckSumAfter \else \PackageWarningNoLine{backref}{% Rerun to get bibliographical references right% }% \fi \endgroup }% } % \end{macrocode} % \end{macro} % % \begin{macrocode} % % \end{macrocode} % % \Finale % \endinput