% \iffalse (meta-comment)
% -----------------------------------------------------------------
% File:   backrefx.dtx
% Author: Danie Els (dnjels@sun.ac.za)
%
% This file is part of the SIstyle package.
%
% Copyright 2004 by Danie Els. All rights reserved.
%
% This work may be distributed and/or modified under the conditions
% of the LaTeX Project Public License, either version 1.3 of this
% license or (at your option) any later version. The latest version
% of the license is in
%      http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2003/12/01 or later.
%
% This work has the LPPL maintenance status "author-maintained".
%
% -----------------------------------------------------------------
% This file contains the documentations and source code for the
% Backrefx package for use with LaTeX2e. See the file 'readme.txt'
% for a list of all the files as well as directions for the
% installation of this package.
% -----------------------------------------------------------------
% \fi
%
% \CheckSum{81}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \iffalse
%<*dtx>
\ProvidesFile{backrefx.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{backrefx}
%<testfile>\ProvidesFile{brefxtest.tex}
%<driver>\ProvidesFile{backrefx.drv}
%\ProvidesFile{backrefx.dtx}
   [2004/07/10  v2.0  Backref enhancements (DNJ Els)]
%<*driver>
\documentclass{ltxdoc}
\usepackage{calc}
\EnableCrossrefs
%\DisableCrossrefs     % say \DisableCrossrefs if index is ready
\CodelineIndex
\RecordChanges         % gather update information
%\OnlyDescription      % comment out for implementation details
%\OldMakeindex         % use if your MakeIndex is pre-v2.9
\setlength\hfuzz{15pt} % dont make so many
\hbadness=7000         % over and under full box warnings
\begin{document}
  \DocInput{backrefx.dtx}
\end{document}
%</driver>
% \fi
%
%
%
% \changes{v1.0}{2002/05/30}{Initial version}
% \changes{v2.0}{2004/07/10}{Update for backref v1.23}
%
%
%  \GetFileInfo{backrefx.dtx}
%
%  \title{Package \textsf{backrefx}\thanks{%
%    This file has version number
%    \fileversion, last revised \filedate.}\\[.75ex]
%    \normalsize(Enhancements for \textsf{backref})}
%
% \author{Danie Els\\
%       \small Department of Mechanical Engineering\\
%       \small University of Stellenbosch, South Africa\\
%              e-mail: \texttt{dnjels@sun.ac.za}}
%
%  \date{\filedate}
%
%  \maketitle
% \noindent\fbox{\parbox{\textwidth-2\fboxsep}{\small%
%    The \textsf{backrefx} package is now obsolete after the
%    release of \textsf{backref} v1.23, because all the functionality
%    are now provided by \textsf{backref}. This release of \textsf{backrefx}
%    is only provided for backward compatibility of existing documents.}}
% \bigskip
%
% \begin{abstract}
%
% \noindent
% The \textsf{backrefx} package enhances the \textsf{backref}
% package of David Carlisle and Sebastian Rahtz. It enables
% \textsf{backref} to print the bibliographic back
% references in a more typographical sound manner (similar to
% the back references in \TeX\ Unbound of Hoenig), for example:
% \begin{tabbing}
% \hspace*{2em}\=\kill
%  \>(Cited on page 10.)\\
%  \>(Cited on pages 10 and 12.)\\
%  \>(Cited on pages 10, 12 and 15.)
% \end{tabbing}
% \end{abstract}
%
%  \tableofcontents
%  \clearpage
%
% \section{Using \textsf{backref} package}
%
% \subsection*{With \textsf{hyperref}:}
%
%  For back references with hyper-links, the \textsf{backref}
%  package is loaded internally by the \textsf{hyperref} package
%  and all the options are set within \textsf{hyperref}:
% \begin{quote}\small
% \begin{tabbing}
% \textsf{hyperref} options:~
%   \=|pagebackref|\= | = [true]| or |false|\\
%   \>|backref|    \> | = [section]|, |slide|, |page|, |none| or |false|.
% \end{tabbing}
% \begin{tabbing}
% |\usepackage[backref=section]{hyperref}|~\=\kill
% |\usepackage[backref]{hyperref}        | \>$\rightarrow$~~Refer to sections of citations.\\
% |\usepackage[backref=section]{hyperref}| \>$\rightarrow$~~Refer to sections of citations.\\
% |\usepackage[backref=slide]{hyperref}  | \>$\rightarrow$~~Refer to sections of citations.\\
% |\usepackage[backref=page]{hyperref}   | \>$\rightarrow$~~Refer to page numbers of citations.\\
% |\usepackage[pagebackref]{backref}     | \>$\rightarrow$~~Refer to page numbers of citations.
% \end{tabbing}
% \end{quote}
% Note that the back reference options must be loaded as part of the
% \textsf{hyperref} package and not as part of the \cmd{\hypersetup}
% options.
%
% \subsection*{Without \textsf{hyperref}:}
%
% To activate back references without any hyper-links, the package
% \textsf{backref} can be loaded with options:
% \begin{quote}\small
% \begin{tabbing}
% |\usepackage[pageref]{backref}|~\=$\rightarrow$~ In terms of sections of reference\kill
% |\usepackage[ref]{hyperref}|     \>$\rightarrow$~Refer to sections of citations.\\
% |\usepackage[pageref]{backref}|  \>$\rightarrow$~Refer to page numbers of citations.
% \end{tabbing}
% \end{quote}
%
% \subsection*{Redefinition of \cmd{\backrefalt}:}
%
% The redefinition of the output to a more typographical sound
% manner can be accomplished with the \cmd{\backrefalt} command
% (see \textsf{backref} documentation). A typical preamble
% with a switch for hyper-links is:
%
% \begin{quote}\small
% |\iftrue                         |\\
% |   \usepackage[backref=page,|\meta{hyperref options} |]{hyperref}|\\
% |   % hyperref dependent packages, e.g. memhfixc|\\
% |\else                           |\\
% |   \usepackage{nohyperref}      |\\
% |   \usepackage[pageref]{backref}|\\
% |\fi                             |\\
% |\renewcommand*{\backref}[1]{}   |\\
% |\renewcommand*{\backrefalt}[4]{%|\\
% |   \ifcase #1 %                 |\\
% |      (Not cited.)%             |\\
% |   \or                          |\\
% |      (Cited on page~#2.)%      |\\
% |   \else                        |\\
% |      (Cited on pages~#2.)%     |\\
% |   \fi}                         |\\
% \verb*|\renewcommand*{\backrefsep}{, }|\\
% \verb*|\renewcommand*{\backreftwosep}{ and~}|\\
% \verb*|\renewcommand*{\backreflastsep}{ and~}|
% \end{quote}
% This will give output in the bibliography
% \begin{quote}
% (Cited on page 10.)\\
% (Cited on pages 10 and 12.)\\
% (Cited on pages 10, 12 and 15.)
% \end{quote}
%
% \section{Usage of \textsf{backrefx} package}
%
% The \textsf{backrefx} package is only provided for backward
% compatibility of existing document. Please do not use it
% for any new documents.
% The \textsf{backrefx} package requires the \textsf{backref}
% packages and only redefines the output formatting.
%
% \subsection*{With \textsf{hyperref}}
% The \textsf{backref} package is loaded internally by
% \textsf{hyperref} and all options are set by \textsf{hyperref}.
% \textsf{Backrefx} must be loaded after \textsf{hyperref} and
% the output format is redefined. This results in hyper-links for
% all the good looking back references.
%
% \begin{quote}
% |\usepackage[|\meta{options}|]{hyperref}|\\
% |\usepackage{backrefx}|\\
% |   \renewcommand*{\backrefpagesname}{...|\\
% |    :|
% \end{quote}
% \begin{quote}
% \begin{tabbing}
% \textsf{hyperref} options:~
%   \=|pagebackref|\= | = [true]| or |false|\\
%   \>|backref|    \> | = [section]|, |page|, |slide|, |none| or |false|.\\
% \end{tabbing}
% \end{quote}
%
%
% \subsection*{Without \textsf{hyperref}}
% The \textsf{backrefx} can be used without \textsf{hyperref}
% if hyper-links is not required.
% \begin{quote}
% |\usepackage[|\meta{options}|]{backrefx}|\\
% |   \renewcommand*{\backrefpagesname}{...|\\
% |    :|
% \end{quote}
% \begin{quote}
% \begin{tabbing}
% \textsf{backrefx} options:~
%   \=|pageref|\quad\= --- refer to page numbers of citations.\\
%   \>|ref|         \> --- refer to sections of citations.\\
% \end{tabbing}
% \end{quote}
%
% \subsection*{Language specific commands}
% The user can redefine the language specific commands to
% suit his or her needs. For example:
% \begin{quote}
%  |\renewcommand{\backrefpagesname}{Cited on page~}|\\
%  |\renewcommand{\backrefpagesnames}{Cited on pages~}|\\
%  |\renewcommand{\backrefsectionsname}{Cited in section~}|\\
%  |\renewcommand{\backrefsectionsnames}{Cited in sections~}|\\
%  |\renewcommand{\backreflist}{\space and~}|\\
%  |\renewcommand{\backrefformat}[1]{(#1.)}|\\
%  |\renewcommand{\backrefnocite}{}|
% \end{quote}
%
%
%  \section{A test file for \textsf{backrefx}}
%
%    \begin{macrocode}
%<*testfile>
\documentclass{book}
\usepackage{natbib}
\iftrue
   \usepackage[backref=page]{hyperref}
   \usepackage{backrefx}
\else
   \usepackage[pageref]{backrefx}
\fi
\renewcommand*{\backrefpagesname}{Cited on page~}
\renewcommand*{\backrefpagesnames}{Cited on pages~}
\renewcommand*{\backrefsectionsname}{Cited in chapter~}
\renewcommand*{\backrefsectionsnames}{Cited in chapters~}
\renewcommand*{\backreflist}{\space and~}
\renewcommand*{\backrefformat}[1]{\textit{(#1.)}}
\renewcommand*{\backrefnocite}{not cited}

\listfiles
\begin{document}
\mainmatter
\chapter{First Chapter}
  It was shown by \citet{els,smith,murphy} that ...\clearpage
\chapter{Second Chapter}
  It was shown \citep{smith,murphy} that ... \clearpage
\appendix
\chapter{First Appendix}
  It was shown by \citet*{murphy} that ...

  \nocite{Jones}

%Remember open lines in bibliography!!!!
\begin{thebibliography}{999}
 \bibitem[Jones(2003)]{Jones}
    Jones, J., (2003),
    \textsl{Test I.}

 \bibitem[Els(1990)]{els}
    Els, D.N.J., (1990),
    \textsl{Test II.}

 \bibitem[Smith(1990)]{smith}
    Smith, J., (1993),
    \textsl{Test III.}

 \bibitem[Murphy et.al.(2000)Murphy and Els]{murphy}
    Murphy, K. and Els, D.N.J., (2000),
    \textsl{Test IV.}

\end{thebibliography}
\end{document}
%</testfile>
%    \end{macrocode}
%
% \StopEventually{}
% \clearpage
% \section{The implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
% \subsection{Options}
%
%   If \textsf{backref} is already loaded (e.g.\ by \textsf{hyperref}), then
%   suppress all local options to prevent conflicts. Otherwise load it
%   with all the local options.
%    \begin{macrocode}
\@ifpackageloaded{backref}%
   {\DeclareOption*{}%
    \ProcessOptions}%
   {\RequirePackageWithOptions{backref}}
%    \end{macrocode}
%
%    \noindent Try to figure out the options \textsf{backref} was loaded with
%    (especially when loaded with \textsf{hyperref}).
%
%    Options that can be used without package \textsf{hyperref}.
%    \begin{macrocode}
\ifx\backrefxxx\page@backref%          (pageref)
  \def\x@backref{\backrefpagesname}%
  \def\x@backrefs{\backrefpagesnames}%
\fi
%    \end{macrocode}
%    \begin{macrocode}
\ifx\backrefxxx\section@backref%       (ref)
   \def\x@backref{\backrefsectionsname}%
   \def\x@backrefs{\backrefsectionsnames}%
\fi
%    \end{macrocode}
%    Back-referencing to be hyper links,
%    by page or section.
%    \begin{macrocode}
\ifx\backrefxxx\hyper@section@backref% (hyperref)
  \def\x@backref{\backrefsectionsname}%
  \def\x@backrefs{\backrefsectionsnames}%
\fi
%    \end{macrocode}
%    \begin{macrocode}
\ifx\backrefxxx\hyper@page@backref%    (hyperpageref)
  \def\x@backref{\backrefpagesname}%
  \def\x@backrefs{\backrefpagesnames}%
\fi
%    \end{macrocode}
%
% \subsection{Local definitions}
%
%    \begin{macro}{\backrefpagesname}
%    \begin{macro}{\backrefpagesnames}
%    \begin{macro}{\backrefsectionsname}
%    \begin{macro}{\backrefsectionsnames}
%    \begin{macro}{\backreflist}
%    \begin{macro}{\backrefformat}
%    \begin{macro}{\backrefnocite}
%    The following text strings commands can be redefined by the
%    user for language or format requirements.
%    \begin{macrocode}
\def\backrefpagesname{Cited on page~}
\def\backrefpagesnames{Cited on pages~}
\def\backrefsectionsname{Cited in section~}
\def\backrefsectionsnames{Cited in sections~}
\def\backreflist{\space and~}
\def\backrefformat#1{(#1.)}
\def\backrefnocite{Not cited}
%    \end{macrocode}
%    (Maybe we need to load a config file?)
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%
%
%    \subsection{Redefining \textsf{backref} commands}
%
%    \begin{macrocode}
\renewcommand*{\backref}[1]{}
%    \end{macrocode}
%
%    \begin{macrocode}
\renewcommand*{\backrefalt}[4]{%
   \ifcase #1 %
      \backrefformat{\backrefnocite}%
   \or
      \backrefformat{\x@backref~#2}%
   \else
      \backrefformat{\x@backrefs~#2}%
   \fi}
%    \end{macrocode}
%
%    \begin{macrocode}
\renewcommand*{\backrefsep}{, }
\renewcommand*{\backreftwosep}{\backreflist}
\renewcommand*{\backreflastsep}{\backreflist}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
\endinput