%    \iffalse meta-comment 
% bibtopic.dtx
% Docstrip archive, run through LaTeX.
% See bibtopic.ins for details on how to produce the style file/documentation.
%
% Copyright (C) 1998-2000 P. Basso, S. Ulrich
% Copyright (C) 2001-2003 S. Ulrich
%
% Please send bug reports to: <stefanulrich@users.sourceforge.net>
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
% 
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
% 
%
%
%<*driver>
\ProvidesFile{bibtopic.drv}[1999/06/01 v1.0 Driver for bibtopic package]
\documentclass[10pt,a4paper]{ltxdoc}
\usepackage[normalwarnings]{bibtopic}
\errorcontextlines\maxdimen
%\usepackage{fullpage}
\RequirePackage{url}%
\RequirePackage{ifthen}%
% \IfFileExists{hyperref.sty}{%
%     \RequirePackage{hyperref}%
% }{}
\GetFileInfo{bibtopic.sty}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\setcounter{IndexColumns}{2}    % make a twocolumn index
\setlength{\columnseprule}{0pt} % no rules between columns ...
\setlength{\columnsep}{2em}     % ... but more spacing instead.
\setcounter{unbalance}{4}
\setlength{\IndexMin}{100pt}
\OnlyDescription  % uncomment this line to suppress printing the source code

\makeatletter
% Change the font for verbatim listings to \footnotesize.
% The following hook is a workaround for a bug in doc.sty v1.9z:
% setting \MacroFont gets overwritten by the \let assignment.
\AtBeginDocument{%
          \renewcommand\MacroFont{\fontencoding\encodingdefault
                                  \fontfamily\ttdefault
                                  \fontseries\mddefault
                                  \fontshape\updefault
                                  \footnotesize}%
          % work around a bug in doc.sty (reported & fixed) where the
          % second \special@index is just \index, causing the
          % pagenumber instead of the code line number being written
          % into the second-level entry after `environments:'
          \def\SpecialMainEnvIndex#1{\@bsphack
                  \special@index{#1\actualchar
                                  {\string\ttfamily\space#1}
                                  (environment)%
                                  \encapchar main}%
                  % changed \index to \special@index and \protect to \string:
                  \special@index{environments:\levelchar{\string\ttfamily\space#1}\encapchar
                                  main}\@esphack}
          \renewcommand\AltMacroFont{\fontencoding\encodingdefault
                                  \fontfamily\ttdefault
                                  \fontseries\mddefault
%                                \fontshape\sldefault
                                  \fontshape\itdefault
                                  \footnotesize}%
                  \let\macro@font=\MacroFont
}%
% don't show underfull hboxes in index/glossary:
\g@addto@macro{\IndexParms}{\hbadness=10000}
\g@addto@macro{\GlossaryParms}{\hbadness=10000}
\makeatother

\begin{document}
  \DocInput{bibtopic.dtx}
%  \PrintIndex
%  \PrintChanges
\end{document}
%</driver>
%
% ^^A See CTAN:tools/filehdr/filehdr.dvi for an explanation for the following stuff
%
% ===================================================================
%  @LaTeX-package-file{
%     version         = "1.0k",
%     date            = "2002/08/22",
%     filename        = "bibtopic.sty",
%     author-1        = "Pierre Basso",
%     email-1         = "Pierre.Basso@lim.univ-mrs.fr",
%     author-2        = "Stefan Ulrich",
%     email-2         = "stefanulrich@users.sourceforge.net",
%     codetable       = "ISO/ASCII",
%     keywords        = "sectioned bibliographies, multiple bibliographies,
%                        bibliographies by topic, bibliographies by topics,
%                        BibTeX",
%     supported       = "yes",
%     docstring       = "User manual and documented source code and for the
%                        LaTeX package bibtopic.sty"
%  }
% ===================================================================
% \fi
%
% 
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
% \DoNotIndex{\if,\ifnum,\ifdim,\ifcat,\ifmmode,\ifvmode,\ifhmode,%
%             \iftrue,\iffalse,\ifvoid,\ifx,\ifeof,\ifcase,\else,\or,\fi,\loop,\do}
% \DoNotIndex{\box,\copy,\setbox,\unvbox,\unhbox,\hbox,%
%             \vbox,\vtop,\vcenter}
% \DoNotIndex{\@empty,\immediate,\write}
% \DoNotIndex{\egroup,\bgroup,\expandafter,\begingroup,\endgroup}
% \DoNotIndex{\divide,\advance,\multiply,\count,\dimen}
% \DoNotIndex{\relax,\space,\string}
% \DoNotIndex{\csname,\endcsname,\@spaces,\openin,\openout,%
%             \closein,\closeout}
% \DoNotIndex{\catcode,\endinput}
% \DoNotIndex{\jobname,\message,\read,\the,\noexpand}
% \DoNotIndex{\hsize,\vsize,\hskip,\vskip,\kern,\hfil,\hfill,\hss}
% \DoNotIndex{\m@ne,\z@,\@m,\z@skip,\@ne,\tw@,\p@}
% \DoNotIndex{\DeclareRobustCommand,\DeclareOption,\newcommand,\newcommand*}
% \DoNotIndex{\newcount,\newif,\newlinechar,\newread,\newtoks,\newwrite}
% \DoNotIndex{\dp,\wd,\ht,\vss,\unskip,\ifthenelse}
%
% ^^A --------------------------------------------------
%
% \CheckSum{1732}
% 
% \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         \~}
%
% 
% ^^A --------------------------------------------------
% ^^A quite a few (I'm afraid) definitions for formatting this
% ^^A documentation ...
% ^^A --------------------------------------------------
% 
% \makeatletter
% \newcommand\writeauxfile[1]{\immediate\write\@auxout{#1}}^^A for the `implementation' boolean
% \hfuzz.5pt ^^A tolerate overfull \hboxes up to this measure
% \renewcommand\floatpagefraction{.8}
% \hyphenation{bib-lio-gra-phy bib-lio-gra-phies}
% \let\MakeUppercase\itshape ^^A I don't like those uppercase headlines ...
% \let\slshape\itshape ^^A ... nor slanted fonts.
% \pagestyle{headings}
% \frenchspacing
% \overfullrule=5pt
% 
% 
% ^^A This command prints the reference set by label #2.
% ^^A #1 and #3 are stuff to be put before and after the formatted reference,
% ^^A so the referencing can be made optional (e.g. for the user interface
% ^^A description) if the code section isn't included. To detect this, we
% ^^A define the flag (= command) \implementation in the .aux file immediately after
% ^^A \StopEventually as `T' and check inside \CodeRef if \implementation
% ^^A is still undefined (working with booleans became too tricky because they
% ^^A would have to be defined before the .aux file is read; defining them inside the
% ^^A .aux file (using a \write) somehow didn't work).
% ^^A The reference is printed as a number in square brackets, in a slightly
% ^^A (1pt) smaller font.
% 
% \newcounter{bt@curr@font@size}
% \newcommand\CodeRef[3]{^^A
%     ^^A compute smaller fontsize:
%     \setcounter{bt@curr@font@size}{\f@size}^^A
%     \addtocounter{bt@curr@font@size}\m@ne\relax^^A
%     \ifx\implementation\undefined
%     \message{.}^^A info
%     \else
%     \message{:}^^A info
%     #1{\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [\printrefs#2,\end]}#3^^A
%   ^^A  #1{\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [\ref{#2}]}#3^^A
%     \fi
% }
% \newcommand\printrefs{}
% \def\printrefs#1,#2\end{^^A
%     \ifthenelse{\equal{#2}{}}{^^A
%         \ref{#1}^^A
%     }{^^A
%         \ref{#1}, ^^A
%         \printrefs#2\end
%     }^^A
% }
% ^^A \ifhave@hyperref
% ^^A \def\lineref#1{\@safe@activestrue\expandafter\@setref\csname r@#1\endcsname\@firstoffive{#1}\@safe@activesfalse}
% ^^A \else
% ^^A \def\lineref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
% ^^A \fi
% 
% ^^A Fake a \CodeRef command for demonstrative purposes:
% \newcommand\ShowCodeRef[1]{^^A
%     \setcounter{bt@curr@font@size}{\f@size}^^A
%     \addtocounter{bt@curr@font@size}\m@ne\relax^^A
%     {\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [#1]}^^A
% }
% \renewcommand\listfigurename{Figures}
% 
% ^^A BibTeX logo (also works for bold, where a simple \scshape would fail)
% \DeclareRobustCommand{\BibTeX}{^^A
%     B\kern-.05em^^A
% ^^A% The following has been taken from the definition of the
% ^^A% \LaTeX macro, see `ltlogos.dtx' 
%     \hbox{$\m@th$^^A % %% force math size calculations
%         \csname S@\f@size\endcsname
%         \fontsize\sf@size\z@
%         \math@fontsfalse\selectfont
%         I\kern-.025emB}^^A
%     \kern-.08em^^A
%     \-\TeX^^A
% }
% 
% ^^A This allows long command names to be hyphenated:
% \begingroup\makeatother\gdef\btAtSign{@}\endgroup
% \def\btAt{\penalty\@M\-\btAtSign\penalty\@M \hskip\z@skip}
% \def\allowhyphens{\penalty\@M \hskip\z@skip}
% \newcommand\BTbegEnv[1]{^^A
%     {^^A
%         \ttfamily\bslash begin^^A
%         \penalty\@M\hskip\z@skip
%         \Obr\Env{\allowhyphens #1}\Cbr
% ^^A  \penalty\@M \hskip\z@skip
%     }^^A
% }
% \newcommand\BTendEnv[1]{^^A
%     {^^A
%         \ttfamily{\bslash end\penalty\@M
%             \hskip\z@skip\Obr\Env{\allowhyphens #1}\Cbr
%             \penalty\@M \hskip\z@skip}^^A
%     }^^A
% }
% 
% \newcommand\Com{^^A
%     \begingroup\catcode`\@\active\btCom
% }
% \newcommand\chCom[1]{^^A
%     \texttt{\string\char`\\#1}^^A
% }
% \newcommand\chEnv{\texttt}
% \newcommand\Env{^^A
%     \begingroup\catcode`\@\active\btEnv
% }
% 
% \begingroup
% \catcode`\@\active
% \gdef\btCom#1{^^A
%     \def@{\btAt}^^A
%     \ttfamily\hyphenchar\font=`\-\bslash #1\endgroup
% }
% \gdef\btEnv#1{^^A
%     \def@{\btAt}^^A
%     \ttfamily\hyphenchar\font=`\-#1\endgroup}
% \endgroup
% 
% \newcommand\Obr{{\ttfamily\char`\{}}
% \newcommand\Cbr{{\ttfamily\char`\}}}
% 
% ^^A Some handy abbreviations (aka `logical markup commands' ...)
% \newcommand\Package[1]{\textsf{#1}}
% \newcommand\ThisPackage{\Package{\filename}}
% \newcommand\File[1]{\texttt{#1}}
% \newcommand\ImportantNote[1]{\textbf{Note: }#1}
% 
% ^^A   to highlight changes that might be important for users:
% \newcommand\UserChange[1]{\mbox{}\marginpar{\raggedleft{#1}}}^^A
% 
% ^^A  description-like environment for describing commands etc.
% \newenvironment{UserCommands}{^^A
%     \begin{list}{}{^^A
%         \renewcommand\makelabel[1]{^^A
%             \parbox[b]{\labelwidth}{^^A
%                 \makebox[0pt][l]{##1}\\ \mbox{}^^A
%             }\hfil\relax
%         }^^A
%         \setlength\labelwidth\parindent
%         \setlength\leftmargin\labelwidth
%         \addtolength\leftmargin\labelsep
%     }^^A
% }{^^A
%     \end{list}^^A
% }
% 
% ^^A  for formatting longish stuff in typewriter font
% \newcommand*\ttsloppy{\spaceskip.333em plus.11em minus.11em}
% \newcommand*\ErrMessage[1]{`{\ttfamily\ttsloppy\hyphenchar\font=`\-#1}'}
% 
% ^^A  for printing background information/less important stuff in a smaller font size:
% \newenvironment{BackgroundNote}{^^A
%     \medskip\footnotesize
% }{^^A
%     \par
% }^^A
% ^^A 
% ^^A  doc.sty doesn't have a command for adding package *options* to the index
% ^^A  (only commands and environments) - define one:
% ^^A 
% \newcommand*\Option[1]{^^A
%     \topsep\MacroTopsep
%     \trivlist
%     \protected@edef\saved@macroname{\string#1}^^A
%     \def\makelabel##1{\llap{##1}}^^A
%     \macro@cnt\@ne
%     \item[\PrintMacroName{#1}]^^A
%     \global\advance\c@CodelineNo\@ne
%     \bt@SpecialMainOptIndex{#1}^^A
%     \global\advance\c@CodelineNo\m@ne
%     \ignorespaces
% }
% 
% \newcommand*\bt@SpecialMainOptIndex[1]{^^A
%     \@bsphack
%     \special@index{^^A
%         #1\actualchar{\string\ttfamily\space#1} ^^A
%         (option)\encapchar main^^A
%     }^^A
%     \special@index{^^A
%         options:\levelchar{\string\ttfamily\space#1}\encapchar main
%     }^^A
%     \@esphack
% }
% 
% ^^A   
% ^^A  To be added manually to the option descriptions in the `user' part of the
% ^^A  doc (we also used the \SpecialUsageIndex and \SpecialEnvIndex commands
% ^^A  directly instead of \DescribeEnv etc. to avoid having too much stuff in the margins).
% ^^A
% \newcommand*\BTSpecialOptIndex[1]{\@bsphack
%     \index{^^A
%         #1\actualchar{\protect\ttfamily#1} (option)^^A
%         \encapchar usage^^A
%     }^^A
%     \index{^^A
%         options:\levelchar{\protect\ttfamily#1}^^A
%         \encapchar usage^^A
%     }^^A
%     \@esphack
% }
% 
% ^^A ----------------------------------------
% ^^A for formatting figures
% ^^A ----------------------------------------
% ^^A
% ^^A A rule to separate figures from the text:
% ^^A
% \newcommand\BegRule[1][]{^^A
%     \ifthenelse{\equal{#1}{}}{^^A
%         \noindent{\makebox[\textwidth][t]{\hrulefill}}^^A
%     }{^^A
%         \noindent{\makebox[\textwidth][t]{\hrulefill\raisebox{-.5ex}{ \small\ttfamily#1 }\hrulefill}}^^A
%     }^^A
% }
% \newcommand\EndRule{\noindent\rule[\baselineskip]{\textwidth}{.6pt}}
% 
% ^^A
% ^^A Here we use the above rules:
% ^^A
% \newenvironment{Filelisting}[1]{^^A
%     \medskip\BegRule[#1]\bgroup\footnotesize\verbatim
% }{^^A
%     \endverbatim
%     \egroup\EndRule
% }
% 
% ^^A
% ^^A redefine captions (some users might not have caption2e installed):
% ^^A
% \newcommand\capfont{\itshape}
% \newcommand\capsize{\small}
% \def\@caption#1[#2]#3{^^A
%     \par
%     \addcontentsline{^^A
%         \csname ext@#1\endcsname^^A
%     }{#1}{\protect\numberline{\csname the#1\endcsname}{\ignorespaces #2}^^A
%     }^^A
%     \begingroup
%         \@parboxrestore
%         \normalsize
%         \@makecaption{^^A
%             {\capfont\capsize\csname fnum@#1\endcsname:}^^A
%         }{^^A
%             {\capsize\ignorespaces #3}^^A
%         }^^A
%         \par
%     \endgroup
% }
% \newdimen\@tempdimb
% \renewcommand\@makecaption[2]{^^A
%     \vskip\abovecaptionskip
%     \sbox\@tempboxa{#1 }^^A
%     \@tempdimb\wd\@tempboxa
%     \sbox\@tempboxa{#1 #2}^^A
%     \ifdim \wd\@tempboxa >\hsize
%     \@tempdima.8\textwidth
%     \centering\parbox{\@tempdima}{#1 #2}
% ^^A           \advance\@tempdima-\@tempdimb
% ^^A           \parbox{\@tempdima}{#2}}
%     \else
%     \global \@minipagefalse
%     \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}^^A
%     \fi
%     \vskip\belowcaptionskip
% }
% 
% ^^A For the example in figure \ref{fig:output}, we need something that looks like a
% ^^A section heading (but with a smaller fontsize, and without stepping the counters).
% ^^A The command `\fakesections' makes the redefinitions required for this, so
% ^^A that we can use the normal `\section' command to get the desired output.
% ^^A (All of this is copied from the standard classes, with the appropriate
% ^^A omissions/changes).
% \newcounter{helpcnt}
% \newcommand\fakesections{^^A
%     \setcounter{helpcnt}{0}
%     \def\section{\@startsection {section}{1}{\z@}^^A
%         {-3.5ex \@plus -1ex \@minus -.2ex}^^A
%         {2.3ex \@plus.2ex}^^A
%         {\normalfont\normalsize\bfseries}}^^A
%     \def\@sect##1##2##3##4##5##6[##7]##8{^^A
%         \ifnum ##2>\c@secnumdepth
%             \let\@svsec\@empty
%         \else
%             \refstepcounter{helpcnt}^^A
%             \protected@edef\@svsec{\@seccntformat{helpcnt}\relax}^^A
%         \fi
%         \@tempskipa ##5\relax
%         \ifdim \@tempskipa>\z@
%             \begingroup
%                 ##6{^^A
%                     \@hangfrom{\hskip ##3\relax\@svsec}^^A
%                     \interlinepenalty \@M ##8\@@par
%                 }^^A
%             \endgroup
%             \csname ##1mark\endcsname{##7}^^A
%         \else
%             \def\@svsechd{^^A
%                 ##6{\hskip ##3\relax \@svsec ##8}^^A
%                 \csname ##1mark\endcsname{##7}^^A
%                 \addcontentsline{toc}{##1}{^^A
%                     \ifnum ##2>\c@secnumdepth \else
%                     \protect\numberline{\csname the##1\endcsname}^^A
%                     \fi
%                     ##7}^^A
%             }^^A
%         \fi
%         \@xsect{##5}^^A
%     }^^A
% }
%    ^^A
%    ^^A  We'd like to have some sort of referencing ability
%    ^^A  to the individual lines of code in the `code' section.
%    ^^A  The problem with this is that the labelling commands should not
%    ^^A  be printed inside the code section, neither in the .dtx nor in the .sty file.
%    ^^A  So we define `+' as active character that will expand to `\linelabel'
%    ^^A  inside the documentation file and will eat its argument inside the .ins file.
%    
%    ^^A  `+' is made active, use this instead:
%    \DeclareRobustCommand\BTplus{+}
%
%    \catcode`\+13\relax
%    \def+#1;{^^A
%    ^^A some info on what's going on:
%        \message{[ln.\number\c@CodelineNo]}^^A
%        \protected@edef\@currentlabel{\number\c@CodelineNo}^^A
%        \label{#1}^^A
%    }
%    \makeatother
%
%    \changes{v0.1}{1998/01/12}{%
%       Rewrite of P. Basso's \Package{bibtopics.sty}
%       and added english documentation
%    }
%    \changes{v0.1a}{1998/01/25}{%
%       Added the `dot' and `slow' options. Removed the
%       first non-optional argument of \texttt{btSect}; \texttt{.aux}
%       file name should now be set by redefining the \chCom{thebtauxfile}
%       command. Using command names instead of list lookup is default now;
%       the `slow' option still uses the lists
%    }
%    \changes{v0.1b}{1998/02/24}{%
%       Replaced `normalheadings' option by `printheadings'
%       to avoid conflict with KOMA classes
%    }
%    \changes{v1.0c}{2000/01/07}{%
%       Added natbib v7 compatibility; some minor changes
%    }
%    \changes{v1.0d}{2000/06/17}{%
%       Fixed bug: \chCom{citation} commands may now
%       contain comma-separated list of strings (as used by cite.sty)
%       instead of one string only.
%       Minor changes in the documentation
%    }
%    \changes{v1.0e}{2000/06/25}{%
%       Made it backref (hyperref.sty) compatible
%    }
%    \changes{v1.0f}{2000/08/22}{^^A
%       Added the `defaultbib' option
%    }
%    \changes{v1.0g}{2000/08/23}{%
%       Removed the checks/warnings w.r.t. `KOMA' classes/no KOMA bibliography
%    }
%    \changes{v1.0h}{2000/09/08}{%
%       Removed restriction that commands between \chCom{begin\{thebibliography\}}
%       and first \chCom{bibitem} were ignored. Removed the \chEnv{btunits} option
%       (no longer needed). Minor changes
%    }
%    \changes{v1.0j}{2000/10/17}{%
%       Fixed problems with babel's redefinition of \chCom{ifthenelse}
%       (with babel, last item inside \chCom{ifthenelse} mustn't be a
%       command taking arguments; see also bug report babel/2625)
%    }
%    \changes{v1.0k}{2002/06/11}{%
%       Fixed a bug with bibitem counter not properly reset by btUnit
%    }
%    \changes{v1.0k}{2002/08/22}{%
%       Fixed an incompatibility with KOMA classes v2.9
%    }
%
% ^^A --------------------------------------------------
%    \title{\ThisPackage}
%    \author{^^A
%        Pierre Basso\\
%        {\texttt{Pierre.Basso@lim.univ-mrs.fr}}
%        \and
%        Stefan Ulrich\\
%        {\texttt{stefanulrich@users.sourceforge.net}}^^A
%    }
%    \date{\filedate\ \fileversion\\[1ex] {\footnotesize CTAN: \url{macros/latex/contrib/supported/bibtopic/}}}
%    \maketitle
% ^^A --------------------------------------------------
%    \begin{abstract}
%    \ThisPackage\ is a revised version of P. Basso's
%    \Package{bibtopics.sty}\footnote{The name has been truncated to
%    fit the 8\BTplus 3 scheme of certain OSes.}.  It allows for
%    bibliographic references which are taken from several \File{.bib}
%    files and written to separate bibliographies by \LaTeX. These
%    bibliographies may be considered as covering different topics
%    (hence the name) or different material (such as references from
%    articles, references from books, \dots). The package works
%    exclusively on the \LaTeX\ side of things; it won't help your
%    with constructing the the different \File{.bib} files for the
%    various topics.\footnote{There are several tools that may
%    help you with doing this; see section~\ref{sec:tools} for details
%    about this.}
%    
%    Besides from offering features the former version didn't have,
%    this version is compatible with various document classes and
%    bibliographic styles (such as the \textsc{KOMA} classes
%    and the \Package{natbib} package). The package works
%    with \LaTeX2e\ only.  It is currently maintained by
%    S.~Ulrich; please send bug reports or feature requests to
%    \texttt{stefanulrich@users.sourceforge.net}.
%
%    
%
%    \end{abstract}
%    
% ^^A --------------------------------------------------
%    \tableofcontents
%    \listoffigures\bigskip
% ^^A --------------------------------------------------
% \iffalse
%    Especially in the humanities there's often a need to have
%    several bibliographies in a document covering different topics or
%    material from different sources; e.\,g., people doing historical
%    studies may want to put their original sources into one
%    bibliography and the secondary writings into another; or one
%    might want to list all articles in one bibliography and books in
%    anoter, and so on.  This package should help you incorporating
%    these different bibliographies into your \LaTeX\ document; the
%    database files for \BibTeX\ will still have to be constructed
%    independently, according to your actual criteria.
% \fi
% ^^A --------------------------------------------------
%    \section{Example of use}\label{sec:example}
% ^^A --------------------------------------------------
%    Here's a short example showing the main features of
%    \ThisPackage. Let's assume that you want to have two separate
%    bibliographies in your document: References to \textit{books}
%    (with \File{books.bib} as bibliography file) and
%    references to \textit{articles} (with \File{articles.bib} as
%    bibliography file).  For brevity, \File{books.bib} shall
%    contain entries for just two citation keys: \texttt{ColBenh:93}
%    and \texttt{Munt:93}, and \File{Articles.bib} shall contain
%    entries for the two keys \texttt{RouxSmart:95} and
%    \texttt{Schwind:96}.\footnote{The \File{.bib} files are contained
%    in the distribution, as well as all the other files mentioned in
%    the example.  So you may have a look at them while reading this,
%    and run \LaTeX/\BibTeX\ on these files yourself.}  Then your
%    input file might look as shown in
%    figure~\ref{fig:input} on page~\pageref{fig:input}.
%
%    
%    To produce a \File{.dvi} file, you'll have to run \LaTeX\ and \BibTeX\ as
%    follows:\smallskip
%
%    {\small\begin{tabular}{@{}l}
%    \File{\$ latex sample}\\
%    \footnotesize \dots\ (\emph{message from \ThisPackage\ to
%       run Bib\TeX\ on `\File{sample1}' and `\File{sample2}'}) \dots\\
%    \File{\$ bibtex sample1}\quad
%           \footnotesize(\emph{Note: Filename without extension!})\\
%    \File{\$ bibtex sample2}\\
%    \File{\$ latex sample}\\
%    \footnotesize\dots\ (\emph{message from \LaTeX: \ErrMessage{Rerun to get references right}}) \dots\\
%    \File{\$ latex sample}
%    \end{tabular}}\medskip
%
% ^^A --- source code for example in next figure ---
%    \begin{figure}
%    \centering
%    \begin{minipage}{.8\textwidth}
%    \BegRule\par\noindent
%    \footnotesize
%    \begin{verbatim}
%    \documentclass[10pt]{article}
%    \usepackage{bibtopic}
%    \begin{document}
%    \bibliographystyle{alpha}
%
%    \section{Testing}
%    Let's cite all the books: \cite{ColBenh:93} and
%    \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
%    
%    \begin{btSect}{books}
%    \section{References from books}
%    \btPrintCited
%    \end{btSect}
%    
%    \begin{btSect}[plain]{articles}
%    \section{References from articles}
%    \btPrintCited
%    
%    \section{Articles not cited}
%    \btPrintNotCited
%    \end{btSect}
%    \end{document}
%    \end{verbatim}
%    \EndRule
%    \end{minipage}
%    \caption[Input file \File{sample.tex}]{Input file \File{sample.tex}\label{fig:input}}
%    \end{figure}
% ^^A ------
% ^^A
%    So there's one extra \File{.aux} file per \Env{btSect}. These
%    files have the same base name as your \LaTeX\ source file, with
%    an additional number that refers to the number of the \Env{btSect}
%    environment in the \LaTeX\ file.\footnote{^^A
%    You can customize this naming scheme; see the
%    description of the \Com{thebtauxfile} command,
%    p.\,\pageref{doc:thebtauxfile}.}
%    You need to run \BibTeX\ on each of these files.
%    The resulting \File{.dvi} file should look like
%    figure~\ref{fig:output} on page~\pageref{fig:output}.
%
%    Some other things to note about this example:
%    \begin{itemize}
%    \item The second (the non-optional) argument
%        of the \Env{btSect} environment specifies
%        the \BibTeX\ source file(s) for the current `topic'.
%    \item Every \Env{btSect} may use its own bibliography style
%        (with some restrictions; see item~\ref{doc:mixing-styles}
%        on page~\pageref{doc:mixing-styles}).
%    \item The standard \LaTeX\ command \cmd{\bibliograpy} doesn't work
%       with \ThisPackage, and is effectively disabled when using the package.
%       Instead, the package has three separate commands \cmd{\btPrintCited}, \cmd{\btPrintNotCited}
%       or \cmd{\btPrintAll} to print the citations:
%    \item \cmd{\btPrintCited}
%       prints all references for the authors who have been cited in
%       the document (for the references from \File{articles}, this is
%       the article by \emph{Roux and Smart}).
%    \item \cmd{\btPrintNotCited} prints references for authors \emph{not}
%       cited in the document (\emph{Schwind} in the example).
%    \item \cmd{\btPrintAll} (not shown in the example) prints all references
%       from the bibliography file, regardless of whether they have been cited or not.
%    \item Unless the package option \Env{printheadings} is specified,
%       the default section titles and running headers of
%       \Env{thebibliography} are suppressed; the user may provide his
%       own titles using \LaTeX's normal sectioning commands
%       (\Com{section} in the example).
%    \end{itemize}
%    
%    
% ^^A --- output of example from previous figure ---
%    \begin{figure}
%    \centering
%    \begin{minipage}{.8\textwidth}
%    \fakesections
%    \BegRule\par\smallskip\noindent
%    \footnotesize
%    \bibliographystyle{alpha}
%
%    \section{Testing}
%    Let's cite all the books: \cite{ColBenh:93}
%    and \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
%    
%    \begin{btSect}{books}
%    \section{References from books}
%    \btPrintCited
%    \end{btSect}
%    
%    \begin{btSect}[plain]{articles}
%    \section{References from articles}
%    \btPrintCited
%    
%    \section{Articles not cited}
%    \btPrintNotCited
%    \end{btSect}
%    \EndRule
%    \end{minipage}
%    \caption[Output from \File{sample.tex}]{Output from \File{sample.tex}}\label{fig:output}
%    \end{figure}
% ^^A ------
%    
% ^^A --------------------------------------------------
%    \section{User interface}
% ^^A --------------------------------------------------
%    After this short example, let's have a more detailed look on the syntax
%    of the user commands.
%
%
% ^^A --------------------------------------------------
%    \subsection{Commands and environments}
% ^^A --------------------------------------------------
%    
%    \begin{UserCommands}
%    \item[\cmd{\bibliographystyle}\marg{style}]\SpecialUsageIndex{\bibliographystyle}
%    This command can be used anywhere (even several times) in the
%    document to set the default bibliography style \meta{style} for
%    the subsequent \Env{btSect} environments.  Examples for
%    \meta{style} are \Env{plain}, \Env{named}, \Env{agsm} etc. --
%    anything for which there exists a \File{.bst} file. (Note that
%    some bibliography styles are incompatible with each other -- see
%    item~\ref{doc:mixing-styles} on page~\pageref{doc:mixing-styles}
%    for more about this.)  So this command is quite similar to the standard
%    \LaTeX\ command with the same name, only that it
%    can be used several times and that a default \meta{style} (= \Env{plain})
%    is used if it doesn't occur at all.
%    The setting
%    specified by this command can be overridden for specific
%    \Env{btSect}s by using \Env{btSect}'s optional argument \meta{style}.
%
%    \item[\cmd{\bibliography}\marg{bib-files}]\SpecialUsageIndex{\bibliography}
%    This command \emph{cannot} be used together with \ThisPackage; in fact, it is disabled
%    and using it will result in a warning. Instead, use one of the commands \cmd{\btPrintCited},
%    \cmd{\btPrintNotCited} and \cmd{\btPrintAll} together with the \Env{btSect} environment
%    (described below).
%
%    \item[\BTbegEnv{btSect}\oarg{style}\marg{bib-files}]^^A
%    \SpecialEnvIndex{btSect}
%    This is the main environment of \ThisPackage. It serves as a
%    `container' for the commands \Com{btPrintCited},
%    \Com{btPrintNotCited} and \Com{btPrintAll} that actually print
%    the bibliographies. The environment determines the style and the
%    \BibTeX\ source file(s) for these references. Its arguments are:
%  
%    \begin{itemize}
%    \item[\meta{style}]
%       optional argument to override the default
%       \Env{bibliographystyle} (see the \Com{bibliographystyle}
%       command) for the scope of the current \Env{btSect}.
%
%    \item[\meta{bib-files}]
%       the filename(s) of the bibliography file(s) from which the
%       references for the current \Env{btSect} are taken. Just as in
%       the standard \Com{bibliography} command of \LaTeX, this
%       argument consists of one filename or a comma-separated list of
%       filenames without the \File{.bib} extension.
%    \end{itemize}
%    \end{UserCommands}
%
%    The following three commands can only be used inside a \Env{btSect} environment.
%    They read the \Env{thebibliography} environment
%    corresponding to the current \meta{bib-files} and print
%    some or all of the entries in it.
%
%    \begin{UserCommands}
%    \item[\cmd{\btPrintCited}]\SpecialUsageIndex{\btPrintCited}
%    Prints all references from \meta{bib-files} that have been cited
%    within the scope of the current \Env{btUnit} environment (or in
%    the entire document, if there is no \Env{btUnit} environment --
%    see the description of the \Env{btUnit} environment below).
%
%    \item[\cmd{\btPrintNotCited}]\SpecialUsageIndex{\btPrintNotCited}
%    Prints all references from \meta{bib-files} for the citations
%    occurring in \meta{bib-files} that have \emph{not} been cited in
%    the current scope.
%
%    \item[\cmd{\btPrintAll}]\SpecialUsageIndex{\btPrintAll}
%    The union of \Com{btPrintCited} and \Com{btPrintNotCited}: prints
%    \emph{all} references from \meta{bib-files}, no matter if they
%    have been cited or not.
%    \end{UserCommands}
%
%    The following environment provides logically independent citation
%    sections, i.\,e. it implements the behaviour you would get from
%    using one of the \Package{chapterbib} or \Package{bibunits}
%    packages (which are incompatible to \ThisPackage).
%
%    \begin{UserCommands}
%    \item[\BTbegEnv{btUnit}]\SpecialEnvIndex{btUnit}\label{doc:btUnit}
%
%    Normally, when you invoke one of the
%    \Com{btPrint\{Cited$\mid$NotCited\}} commands, `cited' means: A
%    reference that has been cited somewhere in the entire document.
%    However, if you enclose a part of your document into the
%    \Env{btUnit} environment, the scope of the citations is
%    narrowed to this environment. This also means that you can have
%    several \Env{btUnit}s containing the same bibliographic reference
%    without getting a \ErrMessage{multiply-defined labels} warning
%    from \LaTeX.
%    An example input file using the \Env{btUnit} environment is shown
%    in figure~\ref{fig:input-btUnit}, p.\,\pageref{fig:input-btUnit}.
%
%    \ImportantNote{When using this environment
%    \emph{all} of your citations have to occur inside some
%    \Env{btUnit}. Citations not in the scope of a \Env{btUnit} won't
%    work at all. Also note that this environment cannot be nested.}
%
% ^^A --- source code: example using btUnit ---
%
%    \begin{figure}
%    \centering
%    \begin{minipage}{.8\textwidth}
%    \BegRule\par\noindent
%    \footnotesize
%    \begin{verbatim}
%    \documentclass[10pt]{article}
%    \usepackage{bibtopic}
%    \begin{document}
%    \bibliographystyle{alpha}
%    
%    \begin{btUnit}         %%% begin first btUnit
%    Let's cite all the books: \cite{ColBenh:93} and
%    \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
%    
%    \begin{btSect}{books}
%    \section{References from books}
%    \btPrintCited
%    \end{btSect}
%    
%    \begin{btSect}[plain]{articles}
%    \section{References from articles}
%    \btPrintCited
%    
%    \section{Articles not cited}
%    \btPrintNotCited
%    \end{btSect}
%    \end{btUnit}           %%% end first btUnit
%    
%    \begin{btUnit}         %%% begin second btUnit
%    We may cite \cite{RouxSmart:95} another time without causing a
%    `multiple defined citations' warning from \LaTeX, since this
%    citation is located in another `btUnit'.
%
%    \begin{btSect}{articles}
%    \section{All articles}
%    \btPrintAll
%    \end{btSect}
%    \end{btUnit}           %%% end second btUnit
%    
%    \end{document}
%    \end{verbatim}
%    \EndRule
%    \end{minipage}
%    \caption[Using the \texttt{btUnit} environment]{Example for using
%       the \Env{btUnit} environment
%       (the output isn't shown).\label{fig:input-btUnit}}
%    \end{figure}
%
%    \end{UserCommands}
%
%    Finally, there's a command for customizing the names of the additional
%    auxiliary files produced by this package -- i.\,e. the \File{.aux} files
%    written by \Env{btSect}, and the \File{.bbl} files produced by
%    running \BibTeX\ on these \File{.aux} files:
%
%    \begin{UserCommands}
%    \item[\cmd{\thebtauxfile}]
%    \mbox{}\SpecialUsageIndex{\thebtauxfile}\label{doc:thebtauxfile}^^A
%    The default definition of this command in \ThisPackage\ looks like this:
%    \begin{verbatim}
%    \def\thebtauxfile{\jobname\arabic{btauxfile}}
%    \end{verbatim}
%    So the basename of the additional auxiliary files is the
%    basename of the \LaTeX\ file (\Com{jobname}) with a counter
%    \Env{btauxfile} appended for uniqueness. This counter is
%    incremented automatically by each \Env{btSect} environment.  This
%    command may be redefined by the user at any place in the input
%    file; such a redefinition will then hold for all subsequent
%    \Env{btSect} environments.  For example, the \Env{dot} package
%    option redefines \Com{thebtauxfile} to include a dot to separate
%    the filename and the number like this:
%    \begin{verbatim}
%    \renewcommand{\thebtauxfile}{\jobname.\arabic{btauxfile}}
%    \end{verbatim}
%    Or if you want the package to use uppercase letters instead of
%    digits, you may redefine \Com{thebtauxfile} in your document
%    preamble like this:
%    \begin{verbatim}
%    \renewcommand{\thebtauxfile}{jobname.\Alph{btauxfile}}
%    \end{verbatim}
%
%    You may also use any descriptive name for \Com{thebtauxfile}; but
%    note that if you don't use the built-in counter \Env{btauxfile},
%    you should double-check that each \Com{thebtauxfile} (for every
%    \Env{btSect}) does have a unique name; otherwise, a later
%    auxiliary file with the same name as the current one would overwrite
%    its contents, and \Package{bibtopic} wouldn't work properly.
%
%    \begin{BackgroundNote}
%    Also note that virtually any naming scheme may cause conflicts
%    with existing \File{.aux} files --
%    e.\,g., \Package{bibtopic} will produce \File{foo1.aux} from
%    \File{foo.tex}; if there also exists another file named
%    \File{foo1.tex}, there is a name clash between the regular \File{.aux}
%    file and the \Package{bibtopic} file. However, this will probably
%    only lead to serious problems when you're \LaTeX ing the files
%    \File{foo.tex} and \File{foo1.tex} at the same time, since \TeX\
%    doesn't lock its auxiliar files, and simultaneous
%    read\slash write operations to the same file may cause a major mess.
%    \end{BackgroundNote}
%
%
%    \end{UserCommands}
%
% ^^A --------------------------------------------------
%    \subsection{Package Options}\label{sec:options}
% ^^A --------------------------------------------------
%    Here is an alphabetical list of all the options of \ThisPackage:
%
%    \begin{description}
%       
%    \item[\Env{breakcites}]\BTSpecialOptIndex{breakcites} Since the
%       \Package{breakcites} package is not compatible with the \Env{btUnit}
%       definition of \ThisPackage\ (see section~\ref{sec:compatibility}), this
%       option may be used instead of the package to get the same behaviour.
%
%    \item[\Env{defaultbib}]\mbox{}\BTSpecialOptIndex{defaultbib}\label{doc:defaultbib}
%       You should use this option as a workaround for the \ErrMessage{unknown bibliography}
%       error (see item~\ref{doc:unknown-thebibliography} on
%       page~\pageref{doc:unknown-thebibliography}) in case you don't want to use
%       some standard package with a `known' definition such as the standard or KOMA classes
%       or \Package{natbib.sty}.
%       This option will replace the (current) definition of \Env{thebibliography}
%       by some built-in default. In this case, a warning is given
%       since the visual appearance of the bibliography might be different.
%       This option does nothing if a known definition of \Env{thebibliography} is used.
%
%    \item[\Env{dot}]\BTSpecialOptIndex{dot}^^A
%       Changes \Com{thebtauxfile} to include an additional dot between the
%       base file name and the number
%       (\File{foo.1.}\{\File{aux}$\mid$\File{bbl}\} instead of
%       \File{foo1.}\{\File{aux}$\mid$\File{bbl}\}; see the description of the
%       \Com{thebtauxfile} command, p.\,\pageref{doc:thebtauxfile} for
%       details).  This naming scheme was used in the old
%       \Package{bibtopics.sty}, so you may use the \Env{dot} option for full
%       compatibility with the old naming scheme.\footnote{The additional
%       dot was omitted in the current version for compatibility reasons with
%       certain OSes that don't support multiple dots in filenames.}
%
%    \item[\Env{normalwarnings}]\BTSpecialOptIndex{normalwarnings}
%       This option turns off the more eye-catching warning about
%       outdated \BibTeX\ files which is the default for
%       \ThisPackage. Normally, a command sequence triggering these
%       warning messages is appended to the \File{.bbl} files
%       included in the document (so that you can't forget or ignore
%       the warning which will last until you relly rebuild the
%       \File{.bbl} file); if you use this option, warning messages
%       about outdated files (\ErrMessage{Package bibtopic Warning:
%       xyz.bbl may be outdated}) will appear only for one \LaTeX\
%       run, and warnings about nonexistant \File{.bbl} files will
%       look more like the default warnigs (\ErrMessage{Package
%       bibtopic Warning: No file sample1.bbl}).  The \File{.bbl}
%       files are left alone. This option might be used to
%       speed up \LaTeX ing and to save disk space with huge
%       \File{.bbl} Files.
%
%    \item[\Env{overridenumbers/dontoverridenumbers}]^^A
%       \BTSpecialOptIndex{overridenumbers}\label{doc:overridenumbers}^^A
%       \BTSpecialOptIndex{dontoverridenumbers}^^A
%       Some \File{.bst} styles store numbers for the bibliographic
%       items in the optional argument of the \Com{bibitem} command,
%       in conflict with continuous numbering of the \Com{bibitem}s
%       for several \Env{btSect} environments that is the default with
%       \ThisPackage. The package tries to catch this and re-activate
%       its own counter, issuing a warning message. Using this option
%       will disable the overriding behaviour (and the warning).
%
%    \item[\Env{printheadings}]\BTSpecialOptIndex{printheadings}^^A
%       By default, the normal titles\slash headings for the
%       bibliography section (\Com{bibname} or \Com{refname}) are
%       suppressed when using \ThisPackage. Use this option to
%       print the headings as ususal.
%
%    \item[\Env{sectcntreset}]\BTSpecialOptIndex{sectcntreset}
%       Reset the numerical label for the bibliography
%       items for each \Env{btSect} environment to `1'. (The default
%       is continuous numbering.)  \ImportantNote{This makes only
%       sense when having at most one \Com{btPrintCited} command in
%       all your \Env{btSect} environments; otherwise, the citation
%       labels in the document won't be unique any more!} The bad
%       thing is that you will get {\bfseries no warning} from \LaTeX\
%       about \ErrMessage{multiply-defined labels} in this case -- so
%       please use this option with care.
%
%    \item[\Env{slow}]\BTSpecialOptIndex{slow}
%       By default each citation key is saved in the hash table of command sequences
%       so that 
%       it can be checked efficiently by the \Com{btPrint...} commands.
%       However, depending on the \TeX\ implementation, the total number of command
%       sequences may be limited; e.\,g. for teTeX 0.4, the
%       limit is 9500, and in order to raise it, you'd need to recompile the binary.
%       TeTeX versions ${}> 0.9$ allow for setting this limit dynamically, as do
%       most other implementations (MikTeX, fpTeX).
%
%       When using this option, a linear list is used instead the internal hash table;
%       this is slower, but will save hash space.
%
%    ^^A 
%    ^^A NOTE: natbib uses a lot of save stack as well, so expect problems
%    ^^A       when running natbib on huge .bib files (> 1000 entries or so).
%    ^^A 
%
%    \item[\Env{unitcntnoreset}]\BTSpecialOptIndex{unitcntnoreset}
%       With this option, the bibitem counter will not be reset for
%       for different \Env{btUnit}s (the default behaviour is to reset
%       the counter at the beginning of a new \Env{btUnit}).
%
%    \item[\Env{verbose}]\BTSpecialOptIndex{verbose}
%       Give some messages about the \Com{bibliographystyle} used for
%       the current \Env{btSect}, and about \File{.bbl} files being
%       marked as outdated. This may be useful if you get confused about which
%       bibliography style is active at the moment.
%
%    \end{description}
%    
%
% ^^A --------------------------------------------------
%    \subsection{Warnings and error messages}\label{sec:warnings}
% ^^A --------------------------------------------------
%
%    Most of the package-specific warnings should be pretty self-explanatory
%    (such as the warning telling you to rerun \BibTeX\ on certain
%    files). As for error messages, we have tried to include
%    explanatory messages (which can be invoked by typing `\texttt{h}'
%    at the error prompt~`\texttt{?}'); most of them will only occur
%    under rare circumstances, so we won't explain them here.
%    If you get some strange errors that you don't understand, please
%    do also have a look at the section `Bugs and Restrictions',
%    p.\,\pageref{sec:bugs}.
%
%    In what follows, we'll explain some of the more non-obvious warning or
%    error messages that you might encounter.
%
%    \begin{enumerate}
%    \item \ErrMessage{Rerun to get indentation of bibitems right.}\\
%       When using multiple bibliographies together with a numerical
%       citation style, the item numbering will add up so that the
%       space reserved for the items for each separate bibliography
%       may be too narrow\CodeRef{ (see the implementation section,
%       \Com{bt@adjust@label} }{code:bt@adjust@label}{ for details)}.
%       This will break the left-alignment of the bibliography items.
%       So we count the number of items printed in the bibliographies
%       and use this number to set the items with correct spacing in
%       the next run.  As for all stuff done via the \File{.aux} file,
%       an additional run may be necessary if the information written
%       to the \File{.aux} file differs from previous runs; and this
%       warning just tells you to do this additional run.
%
%    \item \ErrMessage{No appropriate bibitems found for command ... on line ...}\\
%       (probably together with an \ErrMessage{Empty `thebibliography' environment}
%       warning).  This will occur when a \Com{btPrint\dots} command
%       tries to read entries that don't exist at all. This may be caused by
%       \begin{itemize}
%       \item a previous error of some kind (outdated files, e.\,g.); in this case,
%           just rerun \BibTeX\slash\LaTeX, and the warnings will disappear.
%       \item having included a \Com{btPrintCited} command for a bibliography file
%           from which you didn't cite anything at all, or a \Com{btPrintNotCited} command for a
%           bibliography all references of which had been cited.
%           The command name and the line number included in
%           the warning message should help you with pinpointing the command
%           that caused this warning.
%           The \File{.dvi} file will just contain an empty space where you
%           would expect the bibliography; so having separate headings for each
%           of the bibliographies should help locating the erroneous command, too.
%       \item a \Env{thebibliography} enviroment using an unknown kind of
%           \Com{bibitem}s (see also section~\ref{sec:compatibility}
%           about compatibility with other packages).  You should try
%           to switch to another bibliography style in this case (or
%           tell us of the incompatibility, if you really want to use
%           the same style).
%       \end{itemize}
%
%    \item \ErrMessage{Found unknown thebibliography environment.}\\
%       \label{doc:unknown-thebibliography}^^A
%       This message means that the documentclass or some package used in your
%       document provides a definition of the
%       \Env{thebibliography} environment that \ThisPackage\ cannot handle
%       (it has to change the headings, and, more important, parse the
%       \Com{bibitem}s).
%       The definition is evaluated as late as possible, at the beginning
%       of the \Env{btSect} environment; so any package in the preamble
%       can influence the definition, regardless if it's loaded before or
%       after \ThisPackage.
%       Probably the best solution for this problem is to use a `knonw' bibliography
%       style (the default or the KOMA classes, or \Package{natbib.sty} should all work).
%       If you can't do this,
%       you can try to use the \Env{defaultbib} option that will replace the
%       offending definition with a built-in default (but it will warn you
%       that such a replacement has happened, since the formatting could
%       be different from what you would get without that option; see the description of the
%       option on page~\pageref{doc:defaultbib} for more on this).
%
%    \item \ErrMessage{LaTeX Warning: There were undefined references.}\\
%       With the default referencing
%       mechanism, you may get this warning when there have been
%       changes in the bibliography; but in this case, the warning is always
%       followed by another \LaTeX\ warning saying
%       \ErrMessage{Label(s) may have changed. Rerun to get
%       cross-references right}.\footnote{So whenever this second
%       warning does not show up, you know that you have indeed
%       undefined references in your document.} However, when you use
%       the \Env{btUnit} environment \emph{without} using natbib at the same time,
%       this second warning message won't show up (it will be suppressed
%       by the definitions that prevent `multiple label' warnings). This means
%       that it's best to rerun \LaTeX\ anyway to see if this warning
%       message disappears. If it doesn't, then you'll have indeed
%       undefined references in your document.
%    \end{enumerate}
%    
% ^^A --------------------------------------------------
%    \subsection{Obsolete Commands}
% ^^A --------------------------------------------------
%    \begin{BackgroundNote}
%    The commands described in this section were part of the user
%    interface of former versions of \Package{bibunits.sty}. Since these
%    versions are no longer officially supported, we strongly suggest that you
%    don't use these commands for new documents: They don't share some
%    of the features of the new commands and are provided for backward
%    compatibility only.  The descriptions here are intended mainly to help you
%    with replacing them with the new commands.  \end{BackgroundNote}
%
%    \begin{description}
%    \item[\normalfont\BTbegEnv{bibunit}\oarg{style}]\SpecialEnvIndex{bibunit}
%    Somewhat similar to \Com{btSect}, but the bibliography had to be
%    specified by the \Com{putbib} command (which in itself is no
%    longer supported, since it had been used exclusively in this
%    environment).  The actual bibliography was produced with a
%    \Com{nocite\Obr*\Cbr} command inside the environment, so the full
%    syntax was:\medskip
%
%    {\footnotesize\begin{tabular}{@{}l}
%    \BTbegEnv{bibunit}\oarg{style}                     \\
%    \Com{nocite}\Obr\Env{*}\Cbr                        \\
%    \Com{putbib}\oarg{bib-files}                       \\
%    \BTendEnv{bibunit}
%    \end{tabular}}\medskip
%
%    Instead of using these commands, you may now use the \Com{btSect}
%    environment like this:\medskip
%
%    {\footnotesize\begin{tabular}{@{}l}
%    \BTbegEnv{btSect}\oarg{style}\marg{bib-files}        \\
%    \Com{btPrintAll}                                     \\
%    \BTendEnv{btSect}                                    \\
%    \end{tabular}}
%
%    \item[\normalfont\cmd{\putbib}\oarg{style}]
%    See the \Env{bibunit} environment.
%
%    \item[\normalfont\BTbegEnv{bibtopics}\marg{style}\marg{bib-files}]\SpecialEnvIndex{bibtopics}
%    This command was an alias for the \Env{bibunit} environment above:\medskip
%
%    {\footnotesize\begin{tabular}{@{}l}
%    \BTbegEnv{bibunit}\oarg{style}       \\
%    \Com{nocite}\Obr\Env{*}\Cbr                        \\
%    \Com{putbib}\oarg{bib-files}                       \\
%    \BTendEnv{bibunit}
%    \end{tabular}}\medskip
%
%    It can be replaced with a \Env{btSect} as shown above.
%    \end{description}
%
%^^A ========================================
%^^A This probably serves no real purpose at all ...
%^^A ========================================
%^^A  ^^A --------------------------------------------------
%^^A     \subsection[Referencing bibliography sections (experimental)]{Commands
%^^A            for referencing bibliography sections\\ (experimental)}
%^^A  ^^A --------------------------------------------------
%^^A 
%^^A     When you use a named style and you have huge bibliography
%^^A     sections, it may be helpful for the reader to know in which
%^^A     section he should look for the actual reference. You may want to
%^^A     incorporate the section reference directly into the citation, or
%^^A     refer to it before or after printing the citation label.  For
%^^A     these cases, a special command is provided that sets the command
%^^A     \Com{btretval} to the reference key of the section containing
%^^A     \meta{author-key}:
%^^A     \begin{description}
%^^A     \item[\normalfont\cmd{\btGetVal}\marg{author-key}]\SpecialUsageIndex{\btGetVal}
%^^A     \end{description}
%^^A  ^^A
%^^A     After calling this command, the command sequence \Com{btretval} will
%^^A     contain the value of the section label in which the reference for
%^^A     \meta{author-key} had been produced (by some \Com{btPrint\dots} command).
%^^A     This section label is
%^^A     automatically produced by the \Com{btPrint\dots} commands;
%^^A     the section itself should have
%^^A     been produced by using some \Com{section} command inside the \Env{btSect}
%^^A     environment (see the example in figure~\ref{fig:input}).
%^^A     The value contained in \Com{btretval} may then be used to produce
%^^A     a reference as usual, e.\,g.:
%^^A     \begin{verbatim}
%^^A     \ref{\btretval} % or \pageref{\btretval}
%^^A     \end{verbatim}
%^^A     (You could also use \Com{titleref} command from \Package{titleref.sty}
%^^A     to produce references to the section titles themselves.)
%^^A 
%^^A     For the time being, there is just one user-level frontend to these 
%^^A     commands; it's quite easy to define your own ones along the lines of this
%^^A     example.
%^^A     \DescribeMacro{\btCiteSect}\SpecialUsageIndex{\btCiteSect}
%^^A     The command \Com{btCiteSect}
%^^A     gets the label for citation key |#1| and uses it along with a
%^^A     \Com{cite} command. For the example document in figure~\ref{fig:output},
%^^A     using the command like this:
%^^A     \begin{verbatim}
%^^A     ... see, e.\,g. \btCiteSect{ColBenh:93} ...
%^^A     \end{verbatim}
%^^A     would produce the output:\bigskip
%^^A 
%^^A     \dots\ see, e.\,g. \cite{ColBenh:93} (section~1)\dots\bigskip
%^^A 
%^^A     \noindent since the reference from the book by Benhamou and Colmerauer had
%^^A     been printed in the references section~1.
%^^A 
%^^A     This command is simply defined as:
%^^A     \begin{verbatim}
%^^A     \DeclareRobustCommand\btCiteSect[1]{%
%^^A        \btGetVal{#1}%
%^^A        \cite{#1} (section~\ref{\btretval})%
%^^A     }
%^^A     \end{verbatim}
%^^A     and can be easily adopted for other purposes.  Fancier
%^^A     solutions could be implemented using the first optional argument
%^^A     of \Package{natbib}'s \Com{cite} command; this way, the reference
%^^A     could be integrated into the citation command itself.
%
%^^A     \begin{BackgroundNote}
%^^A     This feature is still considered experimental, since (as you
%^^A     may have gathered from the above description) the user
%^^A     interface lacks some elegance \texttt{;-)}.  The reason for this is that
%^^A     the commands that actually fetch the value of the label for those
%^^A     citation keys are not fully expandable\footnote{Because we use
%^^A     lists for the key-value pairs, we have to work with \cmd{\def}s
%^^A     inside these commands. On the other hand, it seemed to us that
%^^A     setting up labels as it is usually done in \LaTeX\ (by defining
%^^A     command names) could use up too much of \TeX's string pool (which
%^^A     is quite limited on most implementations) for huge
%^^A     bibliographies, so we preferred the solution with lists.}, so we
%^^A     don't have a command that can be called \emph{inside} a \Com{ref}
%^^A     command (expanding to a valid label), which would probably be
%^^A     more convenient for the user; hence the roundabout way with
%^^A     \Com{btretval}.
%^^A     \end{BackgroundNote}
%
%
% ^^A --------------------------------------------------
%    \section{Additional .aux files}\label{sec:aux-files}
% ^^A --------------------------------------------------
%
%    For bookkeeping purposes, \ThisPackage\ creates up to two extra files (apart
%    from the files for each \Env{btSect}):
%    \File{btaux.aux} and \File{btbbl.aux}. The names have been chosen
%    to minimize conflicts with existing (possibly important) user files;
%    to further reduce this danger, \ThisPackage\ adds a short `signature line'
%    (a comment) at the beginning of these files when writing them,
%    and checks for the presence of this line before overwriting a file.
%    If the file is non-empty, but the signature isn't found, an error is raised:
%    \ErrMessage{file ... not written by bibtopic}.
%    In this case, please check whether the file contains anything
%    important, and if so, copy it to a safe place before continuing.
%    (Alternatively, you could also rename the file, or move it to a place where \TeX\
%    can't find it.)
%
% ^^A --------------------------------------------------
%    \section{Compatibility with other packages}\label{sec:compatibility}
% ^^A --------------------------------------------------
%    
%    The package has been tested with current versions of the
%    \textsc{KOMA} classes and current versions of
%    \Package{natbib.sty}.\footnote{For \textsc{KOMA} and \Package{natbib.sty},
%    the versions tested were 2.5c to 2.9 and 6.8c to 7.0, respectively.}
%    Note that just like \ThisPackage\ disables the usual bibliography section
%    headings, it will also disable the `hooks' provided by some packages\slash classes,
%    e.g. for adding introductory or `preamble' text to the bibliography (e.g. \Com{bibpreamble}
%    in \Package{natbib.sty} and current versions of \textsc{KOMA}). Instead
%    of using these hooks, such text should be written directly inside the
%    \Env{btSect} environment.
%    
%    In principle, \ThisPackage\ should work with any
%    document class or bibliography style, but there are some
%    restrictions/exceptions:
%    \begin{itemize}
%    \item \Package{chapterbib.sty}, \Package{bibunits.sty}: These packages
%       implement multiple, logically independent bibliographies.
%       Since they do somewhat similar things (and work on the same
%       commands) as \ThisPackage, they are both incompatible with
%       it. The \Env{btUnit} environment should provide a similar
%       functionality, so use this environment instead.
%    \item \Package{hyperref.sty}:
%       When \Package{hyperref}'s \Env{backref} option
%       is used, \ThisPackage\ has to be loaded \emph{after} hyperref.
%       (The user is warned if this is not the case.)
%       The \Env{backref} option loads the package \Package{backref.sty}, and
%       \ThisPackage\ has been tested with \Package{backref.sty} versions
%       1.16 to 1.19 (1999/04/12--2000/01/19).
%    \item Packages redefining the \Env{thebibliography} environment in a
%       non-standard way: These definitions may cause the parsing
%       mechanism of the \Com{bibitems} to fail.  See the discussion
%       of the \ErrMessage{unknown bibliography} error message
%       (item~\ref{doc:unknown-thebibliography} on
%       page~\pageref{doc:unknown-thebibliography}) and the \Env{defaultbib}
%       option (page~\pageref{doc:defaultbib}) for more about this.
%    \item Packages redefining the \Com{@citex} command (like, e.\,g.
%       \Package{breakcites}) won't work together with \ThisPackage\
%       when the \Env{btUnit} environment is used. Since \ThisPackage\
%       redefines \Com{@citex} as late as possible (inside \Env{btUnit}),
%       it's most likely that the definitions of the other packages will
%       be overwritten.  The case with \Package{breakcites.sty} is dealt
%       with by the \Env{breakcites} option; if you observe this
%       behaviour with other important packages, please email us about
%       them.
%    \item Packages or \File{.bst} styles using non-standard names for
%       bibliography items (other than \Com{bibitem} or
%       \Com{harvarditem}). In this case, parsing the \Com{bibitem}s
%       will also fail, and will result in an empty bibliography.
%       These cases would have to be treated
%       explicitly inside \ThisPackage, so if you know of important
%       packages that have these non-standard item commands, please email us about
%       them.
%    \item \Package{harvard.sty}: We withdrew compatibility with this package
%       in favour of the current versions of \Package{natbib.sty}
%       which has just the same features; so use \Package{natbib} instead.
%    \item
%       Some \File{.bst}-Styles for numerical styles (e.g.
%       \File{plaindin.bst} by K.\,F.\,Lorenzen) incorporate the item number into the
%       optional argument of \Com{bibitem}; hence, the internal
%       counter won't be used and \ThisPackage\ would not be able to
%       manipulate the counter for continuous numbering.  \ThisPackage\
%       tries to recover in this case by ignoring the optional numerical
%       argument and giving a warning.
%       This warning can be turned off by using
%       one of the package options \Env{overridenumbers} or
%       \Env{dontoverridenumbers} (see
%       p.\,\pageref{doc:overridenumbers} above).\footnote{Another
%       possibility is to change the output function of the
%       \File{.bst} file; see the source file \File{bibtopic.dtx},
%       lines~\the\inputlineno ff. for an example.}
%    \end{itemize}
%
% ^^A
% ^^A     The workaround mentioned above:
% ^^A     -------------------------------
% ^^A   
% ^^A      Change the offending \File{.bst} files as follows (of course, you
% ^^A      must rename the style when you make such a change): From the
% ^^A      function formatting the \Com{bibitem}, delete the stuff
% ^^A      formatting the optional argument. Here's an example (from
% ^^A      \File{plaindin.bst}). Change this function:
% ^^A   
% ^^A      FUNCTION {output.bibitem}
% ^^A      { newline$
% ^^A        "\bibitem[" write$
% ^^A        label write$
% ^^A        "]{" write$
% ^^A        cite$ write$
% ^^A        "}" write$
% ^^A        newline$
% ^^A        ""
% ^^A        before.all 'output.state :=
% ^^A      }
% ^^A   
% ^^A      into:
% ^^A   
% ^^A      FUNCTION {output.bibitem}
% ^^A      { newline$
% ^^A           "\bibitem{" write$
% ^^A           cite$ write$
% ^^A           "}" write$
% ^^A           newline$
% ^^A           ""
% ^^A           before.all 'output.state :=
% ^^A      }
% ^^A   
%    
% ^^A --------------------------------------------------
%    \section{Bugs and Restrictions}\label{sec:bugs}
% ^^A --------------------------------------------------
%    
%    
%    \begin{enumerate}
%    \item
%       \BibTeX's cross-referencing doesn't work between items in different
%       \Env{btSect}s. Since \BibTeX\ is run separately on the files corresponding
%       to different \Env{btSect}s, it won't be able to resolve the cross-reference.
%
%    \item
%       \ThisPackage\ doesn't work with the `unsorted' citation
%       styles\label{sec:unsorted} such as \File{unsrt} or
%       \File{unsrtdin}.\footnote{^^A
%       \ThisPackage\ writes global \Com{citation}\Obr\Env{*}\Cbr\
%       commands to its additional \File{.aux} files: When
%       constructing the \File{.aux} file we don't know in which of
%       the possibly several \File{.bib} files some citation will
%       occur. So since there are no specific \Com{citation} commands
%       in the (additional) \File{.aux} files, \BibTeX\ can only apply
%       author-year sorting or print the items in the order they
%       appear in the \File{.bib} file.} Use the package
%       \Package{multibib.sty} instead (see also section~\ref{sec:related-packages}).
%    
%    \item
%       \ThisPackage\ is case sensitive, while \BibTeX\ isn't. That means that
%       while \BibTeX\ treats a \File{.bib} entry like:\par
%       \begin{tabular}{@{}l}
%       |@article{Gnus:98,| \dots\\
%       \end{tabular}\par
%       and a citation |\cite{gnus:98}| as the same key, \ThisPackage\
%       treats them as different keys, and you will get an
%       \ErrMessage{undefined reference} error for the citation command.\footnote{The reason
%       for this restriction is that \BibTeX\ reads the
%       \Com{citation} labels when reading the \File{.aux} file and
%       writes out the keys for the \Com{bibitem} commands it produces
%       accordingly.  However, bibtopic only writes a
%       \Com{citation}\Obr\Env{*}\Cbr\ to the \File{.aux} file, so
%       \BibTeX\ can't access these labels and therefore has to use
%       the spelling from the \File{.bib} file.}
%
%    \item \mbox{}\label{doc:mixing-styles}^^A
%       When mixing several citation styles, it's important to know that
%       numerical citation styles and author-year styles are generally
%       \emph{incompatible} with each other.  This means that the style
%       declared first will always override later re-declarations, since it is
%       globally set at the begin of the document and can't be changed
%       afterwards. Examples for numerical styles in that sense are
%       \Env{plain} and \Env{alpha} (even if the name doesn't sound like it),
%       examples for author-year styles are the `harvard' styles \Env{agsm}
%       and \File{dcu} or the \Env{authordate1-4} style. As for these
%       examples, you may mix \Env{alpha} with \Env{plain}, but not with
%       \Env{agsm} or vice versa.
%
%    \item
%       Having the same reference in several bibliographies in the
%       same \Env{btUnit} (e.\,g., when using both the \Com{btPrintCited}
%       and the \Com{btPrintAll} command to print parts of the same
%       \Env{thebibliography} twice) may lead to problems with
%       labelling:
%       
%       With the numerical or `plain' labelling styles, such multiple
%       references are treated as \emph{different keys}, i.e. they
%       receive different numbers.
%       
%       With \Package{natbib.sty}, things are a bit different: Multiple
%       references will get the same number; but the numbering will
%       have \emph{gaps} since the repeated entries will be assigned the
%       number of the \emph{last} \Com{bibcite} enty of the \File{.aux}
%       file of that repeated entry.  You will also get warnings
%       about \ErrMessage{multiply defined citations}, and the warning
%       \ErrMessage{Rerun to get citations correct} will appear after each
%       \LaTeX\ run.
%       
%       The latter problem can be avoided by switching to alphabetical or
%       author-year styles, but the warnings about \ErrMessage{multiply
%       defined citations} will remain. To get rid of these, you would need
%       to use \Env{btUnit}s and put the \Com{btPrintAll} and the
%       \Com{btPrintCited} command into different \Env{btUnit}s (see
%       figure~\ref{fig:input-btUnit} on page~\pageref{fig:input-btUnit}
%       for an example).
%
%
%^^A     \item 
%^^A     Sometimes, \BibTeX\ is putting \Com{newcommand}s into the
%^^A     \File{.bbl} file; if you input such a file several times, \LaTeX\
%^^A     will give the error message \ErrMessage{Command xyz already
%^^A     defined}. Currently the only workaround is to change the
%^^A     \Com{newcommand} manually to a \Com{renewcommand} or (even
%^^A     better) to a \Com{providecommand} in the \File{bbl} file.
%
%    \item
%       Switching from one bibliographic style file to another may cause
%       compiling errors (due to the outdated \File{.aux} and \File{.bbl}
%       files). Try to make \LaTeX\ ignore these errors by
%       responding~`\texttt{r}' after the help prompt~`\texttt{?}' (don't
%       quit with~`\texttt{x}', because you want the \File{.aux} file to
%       be regenerated); if all fails, delete the \File{.aux} and
%       \File{.bbl} files before the next \LaTeX\ run.
%
%    \item
%       Brackets in the \File{.bib} file: The brackets `\Env{[]}' are
%       special to \LaTeX\ in that they denote the bounds of an optional
%       argument, and \Com{bibitem} uses such an optional argument
%       for the item labels.  Therefore using brackets `\Env{[...]}'  in
%       a \File{.bib} file entry which is used for sorting may mangle
%       the \Com{bibitem} command.  In this case, hide the brackets from
%       \LaTeX\ by enclosing them in another pair of braces, like this:
%       `\verb|{[...]}|'. (\ThisPackage\ will try to detect such misleading
%       brackets an warn you about them.)
%    \end{enumerate}
%
% ^^A --------------------------------------------------
%    \section{If you're not a user of \BibTeX\ \dots}
% ^^A --------------------------------------------------
%    
%    \dots\ (which would be a pity, though), the feature of
%    selecting only those items actually cited in the document might
%    come in handy: All you'll have to do is provide a sorted
%    \Env{thebibliography}, and \ThisPackage\ will be able to select
%    the needed citations.  The
%    easiest way to use this is to put your \Env{thebibliography}
%    environment into a separate file (call it \File{mybib.bbl}) that
%    can be included using the standard \Env{btSect} environment like,
%    e.\,g.:
%    
%    {\footnotesize
%    \begin{verbatim}
%    \renewcommand{\thebtauxfile}{mybib}
%    \begin{btSect}{}
%    \btPrintCited
%    \end{btSect}
%    \end{verbatim}}
%  ^^A    
%    In this case, the second argument of \Env{btSect} serves no
%    purpose and may as well be left blank. It'll be also a good
%    idea to turn off persistent warnings from \ThisPackage\ by using
%    the \Env{normalwarnings} option -- else, an additional `warning
%    line' might be appended to your \File{mybib.bbl} in the first
%    \LaTeX\ run: \ThisPackage\ will realize that the \File{.aux} file
%    has changed\CodeRef{ (see the implementation section,
%    \Com{bt@cmp} }{code:bt@if@files@differ}{ for details)}, and it will tell you
%    to rerun \BibTeX\ to update your \File{.bbl} File. {\bfseries
%    Don't do that:} Running \BibTeX\ as advertised would overwrite
%    your handwritten \File{.bbl} file with an \emph{empty}
%    bibliography!  With the \Env{normalwarnings} option, this message
%    won't occur; otherwise, you'd have to delete the `warning' line
%    from \File{mybib.bbl} manually in order to get rid of these
%    recurrent warnings.
%
% ^^A --------------------------------------------------
%    \section[Other useful tools]{Other tools that might be useful with\\ \ThisPackage}\label{sec:tools}
% ^^A --------------------------------------------------
%
%    You'll probably need to split up your exitsting \File{.bib}
%    file(s) when switching to \ThisPackage. This section lists
%    some utilities that might be useful for this task. Some of these
%    tools can be used for other purposes, too -- like sorting,
%    merging, consistency checks, automatic key generation etc.; but
%    here we'll concentrate on the extraction issue only.
%
%    Note that if you want to keep all your references together in one
%    master \File{.bib} file, you can always use a dummy attribute
%    that will be ignored by \BibTeX\ but may be used as a key for
%    selecting entries with one of the tools mentioned here.
%    
%    \begin{itemize}
%    \item
%       \textsc{BibTool} (available as C source code on CTAN:
%       \url{biblio/bibtex/utils/bibtool/}).  It allows you to
%       specify regular expressions for extracting entries from a
%       \File{.bib} file.  For example, the following command extracts
%       all `online documents' (items containing the string
%       \Env{http:} or \Env{ftp:} in any field) from \File{mybib.bib}
%       and writes them to a newly created bibliography file
%       \File{online.bib} (the single quotes are needed with some Unix
%       shells to prevent unwanted expansion of braces):\par
%       \begin{tabular}{@{}l}
%       |bibtool -- 'select{"[hf]t?tp:"}' mybib.bib -o online.bib|
%       \end{tabular}
%    \item
%       btOOL (C\slash Perl library, available from:
%       \url{biblio/bibtex/utils/btOOL/}; more documentation can be
%       obtained from the author's home page:
%       \url{http://starship.python.net/~gward/btOOL/}).  A powerful
%       library for writing Perl scripts that manipulate \File{.bib}
%       files. Very flexible, but requires Perl programming skills.
%    \item
%       \File{bibextract} (shell and awk scripts, available from:
%       \url{biblio/bibtex/utils/bibextract/}).  Similar to
%       \textsc{BibTool}, it lets you use regular expressions to extract
%       entries from a \File{.bib} file. With \File{bibextract}, the
%       example above would look like this:\par
%       \begin{tabular}{@{}l}
%       |bibextract "" "[hf]t?tp:" mybib.bib > online.bib|
%       \end{tabular}
%    \end{itemize}
%    
% ^^A --------------------------------------------------
%    \section{Related Packages}\label{sec:related-packages}
% ^^A --------------------------------------------------
%
%    There are several packages with a similar purpose as \ThisPackage:
%    
%    \begin{description}
%    \item[\Package{multibib.sty}:] This package provides similar
%    functionality as \Package{bibtopic}, but with a different approach
%    for the user interface: Instead of splitting up the \File{.bib} files,
%    you use different, bibliography-specific citation commands.
%    In contrast to \ThisPackage,
%    \Package{multibib.sty} can also deal with `\texttt{unsorted}'
%    bibliography styles  (see page~\pageref{sec:unsorted} above).
%
%    \item[\Package{chapterbib.sty}, \Package{bibunits.sty}:]
%    These provide multiple bibliographies as well;
%    the main difference is that with these packages different
%    parts of a document can have their own dedicated bibliography
%    which is independent from the other bibliographies, whereas
%    \Package{bibtopic}\slash\Package{multibib}
%    provide a global bibliography divided into
%    sections.
%
%    \item[\Package{Camel}:]
%    Along with many powerful additional features, this larger package also
%    contains macros for sectioned bibliographies; the
%    user interface is quite different from standard
%    \LaTeX\ (e.\,g., the \Com{cite} command is replaced by a
%    \Com{source} command).
%    \end{description}
%
% ^^A --------------------------------------------------
% ^^A Place to stop if implementation shouldn't be printed
% ^^A --------------------------------------------------
%
%    \StopEventually{\relax}
%    \writeauxfile{\string\gdef\string\implementation{Y}}
%
% ^^A --------------------------------------------------
%    \section{Implementation}\label{sec:sourcecode}
% ^^A --------------------------------------------------
%
%    Some conventions: All commands in this package use the prefix `\Env{bt}' to identify them
%    as belonging to \ThisPackage. Internal commands are prefixed with
%    `\Env{\mbox{bt@}}'; ^^A don't hyphenate this one ...
%    user interface commands use mixed upper-/lowercase letters.
%    (After the fact I heard these were reserved for the \LaTeX\ API, so maybe
%    this wasn't such a brilliant idea after all. It's too late to change it now,
%    however ...)
%     Numbers in square brackets
%    (like `\ShowCodeRef{136}') refer to the line numbers on the left margin.
%
%    Parts tagged with the \Module{debug} flag are included in debugging
%    versions only; production versions will not contain these parts.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    1996/12/01 is the oldest \LaTeX\ version with which this package has been tested.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1996/12/01] \ProvidesPackage{bibtopic}[2002/08/22 v1.0k
Sectioned Bibliographies]
%    \end{macrocode}
%
% ^^A --------------------------------------------------
%    \subsection{Some help commands} 
% ^^A --------------------------------------------------
%
%    \begin{macro}{\bt@debug}
%    Uncommenting the \Com{@debug@true} line will
%    log all the debugging messages to the terminal.
%    You may also log only selected messages by
%    specifying an optional argument to any of the
%    \Com{bt@debug} commands in the style file itself.
%    The debugging code is only included when \File{docstrip}
%    is run with the \Env{debug} option specified.
%    \begin{macrocode}
%<*debug>
\newif\bt@ifdebug
%%% \bt@debugtrue % uncomment this line to activate global debugging
\newcommand*\bt@debug[2][]{%
    \bt@ifdebug
       \PackageInfo{bibtopic}{#1}%
       \typeout{DBG: #2}%
    \else
        \ifx#1\@empty\else
            \typeout{DBG (#1): #2}%
        \fi
    \fi
}
%</debug>
%    \end{macrocode}
%    \end{macro}
%    \Package{ifthen.sty} is needed for many \Com{ifthenelse} constructs. It uses
%    the scratch commands \Com{@tempa} etc. frequently, so we define our own scratch
%    commands as to not interfere with these.
%    \begin{macrocode}
\RequirePackage{ifthen}
\newcommand\bt@tempa{}
\newcommand\bt@tempb{}
\newcommand\bt@tempc{}
\newcommand\bt@args{}
%    \end{macrocode}
%    \begin{macro}{\bt@info}
%    \begin{macro}{\bt@infoNoLine}
%    Macros for less important messages that should only
%    be printed when the package option \Env{verbose} is set (see there,
%    \CodeRef{}{code:verbose}{}).
%    \begin{macrocode}
\newcommand*\bt@info{\@gobble}
\newcommand*\bt@infoNoLine{\@gobble}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%    \begin{macro}{\bt@gobblethree}
%    Analogous to \LaTeX's \Com{@gobbletwo}.
%    \begin{macrocode}
\newcommand\bt@gobblethree[3]{}
%    \end{macrocode}
%    \end{macro}
%
%
% ^^A --------------------------------------------------
%    \subsection{Allocations}
% ^^A --------------------------------------------------
%    \subsubsection{Booleans}
% ^^A --------------------------------------------------
%    Check for \Package{natbib.sty}:
%    \begin{macrocode}
\newif\ifbt@natbib
%    \end{macrocode}
%    Check for presence of one of the \Package{scr*} classes (aka KOMA):
%    \begin{macrocode}
\newif\ifbt@koma@class
%    \end{macrocode}
%    Switch to deal with the `backref' option of \Package{hyperref.sty}:
%    \begin{macrocode}
\newif\ifbt@brf
\newif\ifbt@after@brf
%    \end{macrocode}
%    A global switch that says that a given element is in a list
%    (set by \Com{bt@testelem}, used e.\,g. in \Com{bt@add@elem}):
%    \begin{macrocode}
\newif\ifbt@elem
%    \end{macrocode}
%    Switch for error checking inside the \Env{btSect} environment:
%    \begin{macrocode}
\newif\ifbt@inside@sect
%    \end{macrocode}
%    Switch for error checking inside the \Env{btUnit} environment:
%    \begin{macrocode}
\newif\ifbt@inside@unit
%    \end{macrocode}
%    The following three switches are used along with \Com{bt@call@item}.
%    First a flag for checking if any items have been found at all:
%    \begin{macrocode}
\newif\ifbt@found@item
%    \end{macrocode}
%    True if we have to print only the cited items:
%    \begin{macrocode}
\newif\ifbt@print@cited
%    \end{macrocode}
%    True if we have to print all items (needed if we
%    parse the items for the keyval stuff):
%    \begin{macrocode}
\newif\ifbt@print@all
%    \end{macrocode}
%    Switch for compatibility with older versions of
%    \Package{bibtopics} (may be set inside the document):
%    \begin{macrocode}
\newif\if@globalbiblio
%    \end{macrocode}
%
% ^^A --------------------------------------------------
%    \subsubsection{Counters etc.}
% ^^A --------------------------------------------------
%
%    Since \TeX\ is notoriously short of count registers, most of the counters used
%    are no real counters, but command sequences holding integer values.
%    Here's a command to globally increment such a fake counter:
%    \begin{macro}{\bt@stepcnt}
%    \begin{macrocode}
\newcommand\bt@stepcnt[1]{%
     \@tempcnta#1
     \advance\@tempcnta\@ne
     \protected@xdef#1{\the\@tempcnta}%
}
%    \end{macrocode}
%    \end{macro}
% ^^A
%    This is the only `real' counter: \Env{btauxfile} is the current number of the
%    \Env{btSect} environment; the representation \Com{thebtauxfile} is the full basename
%    of the \File{.aux} and {.bbl} files to be used. (It's a real counter to make it
%    easier for users to redefine \Com{thebtauxfile}.)
%    \begin{macrocode}
\newcounter{btauxfile}
\def\thebtauxfile{\jobname\arabic{btauxfile}}
%    \end{macrocode}
%    To produce more than one citation list (if there's more than one \Env{btUnit}),
%    \Com{bt@unit@cnt} is appended to the listname \Com{bt@sect} (see the command
%    \Com{reset@bt@sect}). It is initialized with 1 here:
%    \begin{macrocode}
\newcommand\bt@unit@cnt{1}
%    \end{macrocode}
%    Numbering used for the labeling commands by the keyval stuff:
%    \begin{macrocode}
\newcommand\bt@internal@sect@cnt{0}
%    \end{macrocode}
%    Number of all bibitems seen so far (possibly in sevaral
%    \Env{btUnit}s):
%    \begin{macrocode}
\newcommand\bt@helpctr{0}
%    \end{macrocode}
%    Total number of bibitems in \emph{all} bibliographies,
%    read from the \File{.aux} file:
%    \begin{macrocode}
\newcommand\bt@totalctr{0}
%    \end{macrocode}
%
% ^^A --------------------------------------------------
%    \subsubsection{Filehandles}
% ^^A --------------------------------------------------
%    \begin{macrocode}
\newread\bt@infilea
\newread\bt@infileb
\newwrite\bt@outfile
%    \end{macrocode}

% ^^A --------------------------------------------------
%    \subsection{Package options}\label{sec:PackageOptions}
% ^^A --------------------------------------------------
%
%    \Option{btunits}\label{code:btunits}^^A
%    This option is obsolete and defined here only for backwards compatibility.
%    \begin{macrocode}
\newif\ifbt@btunits
\DeclareOption{btunits}{%
    \PackageWarningNoLine{bibtopic}{ignoring obsolete `btunits' option}
}
%    \end{macrocode}
%
%    \Option{defaultbib}
%    Option to ignore `unknown thebibliography' errors by providing
%    a fallback definition.
%    \begin{macrocode}
\newif\ifbt@fallback@thb
\DeclareOption{defaultbib}{%
    \global\bt@fallback@thbtrue
}
%    \end{macrocode}
%
%    \Option{verbose}
%    This option makes the \Com{bt@info} messages appear on the screen.  We
%    just change the meaning of \Com{bt@info} and \Com{bt@infoNoLine} from the
%    default \Com{@gobble} to the verbose behaviour.
%    \begin{macrocode}
\DeclareOption{verbose}{%    +code:verbose;
    \def\bt@info#1{%
        \begingroup
            \def\MessageBreak{^^J(bibtopic)\@spaces\@spaces\@spaces}%
            \set@display@protect
            \immediate\write\@unused{%
                ^^JPackage bibtopic info: #1\on@line.^^J%
            }%
        \endgroup
    }%
    \def\bt@infoNoLine#1{%
        \begingroup
            \def\MessageBreak{^^J(bibtopic)\@spaces\@spaces\@spaces}%
            \set@display@protect
            \immediate\write\@unused{%
                ^^JPackage bibtopic info: #1.^^J%
            }%
        \endgroup
    }%
}
%    \end{macrocode}
%
%    \Option{breakcites}
%    This option can be used instead of including the \Package{breakcites} package,
%    which is incompatible to \ThisPackage\ if the \Env{btUnit} environment
%    is used.
%    \begin{macrocode}
\newif\ifbt@breakcites
\DeclareOption{breakcites}{%
    \global\bt@breakcitestrue
}
%    \end{macrocode}
% ^^A
%    \Option{normalwarnings}
%    Option for not hard-coding warnings in the .bbl files;
%    this will make the warnings to rerun \BibTeX\ only appear once.
%    Useful if you don't want to have your .bbl files modified.
%    \begin{macrocode}
\newif\ifbt@normalwarnings
\DeclareOption{normalwarnings}{%
    \global\bt@normalwarningstrue
}
%    \end{macrocode}
% ^^A
%    \Option{printheadings}\label{code:printheadings}
%    Don't suppress the default bibliography headings (suppressing them
%    is the default).
%
%    \begin{macrocode}
\newif\ifbt@printheadings
\DeclareOption{printheadings}{%
    \global\bt@printheadingstrue
}
%    \end{macrocode}
% ^^A
%    \Option{unitcntnoreset}
%    Option to not reset the bibitem counter for new \Env{btUnit}s:
%    \begin{macrocode}
\newif\ifbt@part@cont@ctr
\DeclareOption{unitcntnoreset}{%
    \global\bt@part@cont@ctrtrue
}
%    \end{macrocode}
%
% ^^A
%    \Option{sectcntreset}
%    Option to reset the bibitem counter for new \Env{btUnit}s:
%    \begin{macrocode}
\newif\ifbt@sectctr@reset
\DeclareOption{sectcntreset}{%
    \global\bt@sectctr@resettrue
}
%    \end{macrocode}
%
% ^^A
%    \Option{slow}
%    Option to select bibitems by linear search in a list of keys instead of
%    hashing on the keys.
%    \begin{macrocode}
\newif\ifbt@fast
\bt@fasttrue
\DeclareOption{slow}{%
    \global\bt@fastfalse
}
%    \end{macrocode}
%
% ^^A
%    \Option{dot}
%    Compatibility with earlier versions: separate the counter from the file
%    name in additional files by a dot.
%    \begin{macrocode}
\DeclareOption{dot}{%
   \def\thebtauxfile{\jobname.\arabic{btauxfile}}%
}
%    \end{macrocode}
%    \Option{overridenumbers}
%    Ignore the numbering in the optional argument of \Com{bibitem} (default
%    is to warn in this case).
%    \begin{macrocode}
\newif\ifbt@warn@override
\bt@warn@overridetrue
\newif\ifbt@override@numargs
\bt@override@numargstrue
\newif\ifbt@overridden@numargs
\DeclareOption{overridenumbers}{%
    \bt@warn@overridefalse
    \bt@override@numargstrue
}
%    \end{macrocode}
%    \Option{dontoverridenumbers}
%    \emph{Don't} ignore the numbering in the optional argument of
%    \Com{bibitem} (opposite of previous option; default is to warn
%    in this case).
%    \begin{macrocode}
\DeclareOption{dontoverridenumbers}{%
    \bt@warn@overridefalse
    \bt@override@numargsfalse
}
%    \end{macrocode}
%
%    \begin{macrocode}
\ProcessOptions*
%    \end{macrocode}

% ^^A --------------------------------------------------
%    \subsection{Commands}
% ^^A --------------------------------------------------
% ^^A
%
%    \begin{macro}{\bt@isnum}
%    Check if the argument is a number; evaluate the second argument if so;
%    evaluate the third argument if not. The \Com{ifnum} trick is by D. Arseneau,
%    \url{<21JUL199715321021@reg.triumf.ca>}):
%    \begin{macrocode}
\newcommand\bt@isnum[1]{%
    \if!\ifnum9<1#1!\else_\fi
        \expandafter\@firstoftwo
    \else
        \expandafter\@secondoftwo
    \fi
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@sect@ref@list}
%    A list of authors referenced in a \Env{btSect}. Used by the
%    keyval stuff (see
%    \Com{btSect} \CodeRef{}{code:bt@sect@ref@listReset}{}
%    and \Com{bt@do@print@item} \CodeRef{}{code:bt@sect@ref@listAdd}{}).
%    \begin{macrocode}
\newcommand*\bt@sect@ref@list{}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@curr@cmd}
%    Macro to save the user command that led to an `empty
%    thebibliography' error (used in \Com{bt@bibitemcheck}, see
%    \CodeRef{}{code:bt@curr@cmd}{}; this is set by
%    the \Com{btPrint...} commands.
%    \begin{macrocode}
\newcommand\bt@curr@file{}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@curr@line}
%    Save line number of \Com{bt@curr@cmd} for later use (used with previous macro).
%    \begin{macrocode}
\newcommand\bt@curr@line{}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@kv@req@list}
%    List to save keys that have been requested by the keyval
%    user commands; only those keys will be written
%    to \Com{bt@sect@ref@list}.
%    \begin{macrocode}
\newcommand*\bt@kv@req@list{}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@curr@bib@file}
%    Store the name of the current \File{.bib} file; needed in error message.
%    \begin{macrocode}
\newcommand*\bt@curr@bib@file{}
%    \end{macrocode}
%    \end{macro}
% ^^A
%    \begin{macro}{\bt@cited@list}
%    List of all cited authors. Accessed by \Com{btPrintCited} and
%    \Com{btPrintNotCited} to check if a given author has been cited.
%    \begin{macrocode}
\newcommand*\bt@cited@list{}
%    \end{macrocode}
%    \end{macro}
% ^^A
%    \begin{macro}{\bt@warn@files}
%    List of \File{.bbl} files (needed in warnings); see e.\,g. \Com{bt@files@warnings},
%    section~\ref{sec:PackageWarnings}, p.\,\pageref{sec:PackageWarnings}
%    \begin{macrocode}
\newcommand*\bt@warn@files{}
%    \end{macrocode}
%    \end{macro}
% ^^A
%    For saving the first argument of \Env{thebibliography};
%    possibly modified (for width correction) and used in calls to \Com{bt@savebib}:
%    \begin{macrocode}
\newcommand*\bt@label{}
%    \end{macrocode}
% ^^A
%    \begin{macro}{\bt@globalstyle}
%    \begin{macro}{\bt@defaultstyle}
%    The global bibliographystyle selected by \Com{bibliographystyle};
%    defaults to \Com{bt@defaultstyle} if none is selected:
%    \begin{macrocode}
\newcommand*\bt@globalstyle{}%
\newcommand*\bt@defaultstyle{plain}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    We'll redefine the \Com{citation} command to add its argument (the citation key)
%    to a list of references (\Com{bt@cited@list}).\footnote{Maybe one could have used
%    \Com{@ifundefined\Obr b@\bslash @citeb \bslash extra@b@citeb\Cbr} instead, but the list thing seemed
%    more straightforward.} First we save the original meaning of \Com{citation} in
%    \Com{@bt@oldcitation} (it's just \Com{@gobble} in standard \LaTeX, and evaluated
%    only by \BibTeX, but who knows \dots):
%    \begin{macrocode}
\newcommand*\@bt@orig@citation{}
%<debug>\bt@debug{saving meaning of \string\citation : \meaning\citation}%
\let\@bt@orig@citation\citation
%    \end{macrocode}
% ^^A
%    \begin{macro}{\citation}
%    This command is redefined to add its argument (the citation key) to
%    a list of keys (specific to the current \Com{btUnit}). Definine
%    the command separately for each case (a slight optimization avoiding
%    to branch on the \Env{@bt@fast} option each time it is called).
%    \begin{macrocode}
\ifthenelse{\boolean{bt@fast}}{%
   \def\citation#1{%
      \@for\bt@tempa:=#1\do{%
        \def\@extra@b@citeb{\bt@unit@cnt}%
%    \end{macrocode}
%    For the \Env{fast} case, we define a command name:
%    \begin{macrocode}
        \global\@namedef{\bt@tempa bt@\@extra@binfo}{}%
%<debug>        \bt@debug{defining \bt@temp bt@\@extra@binfo}%
%    \end{macrocode}
%    In both cases, we call the original \Com{citation} command:
%    \begin{macrocode}
        \@bt@orig@citation{\bt@tempa}%
      }%
   }%
}{%
   \def\citation#1{%
      \@for\bt@tempa:=#1\do{%
        \def\@extra@b@citeb{\bt@unit@cnt}%
        \bt@add@elem{\bt@tempa}{\bt@cited@list}%
        \@bt@orig@citation{\bt@tempa}%
      }%
   }%
}
%    \end{macrocode}
%    \end{macro}
%
%    To suppress warnings about \ErrMessage{multiply defined labels} caused by
%    multiple occurrences of the same label in different \Env{btUnit} environments,
%    we redefine \Com{bibcite} just like \Package{chapterbib.sty} does it.
%    In consequence, also the \Com{@citex} and \Com{nocite} commands have to be
%    redefined; but this is only done in case the \Env{btUnit} environment is
%    indeed used.
%    (This code is copied directly from \Package{chapterbib.sty}; we included the hooks
%    \citeform and \Com{citepunct} and added our own |\bt@citesurround| to
%    implement the \Env{breakcites} option.)
%    \begin{macro}{\bt@citesurround}
%    \changes{v1.0j}{2000/10/17}{%
%        Added argument (babel\slash \chCom{ifthenelse} bug)
%    }
%    \begin{macrocode}
\newcommand*\bt@citesurround{}%

\def\bt@citesurround#1{%
    \ifthenelse{\not\boolean{bt@breakcites}}{%
        \hbox{#1}%
    }{%
        #1%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
\@ifundefined{citeform}{\let\citeform\relax}{}
\@ifundefined{citepunct}{\def\citepunct{,\penalty\@m\ }}{}
%    \end{macrocode}
%    Set a flag when \ThisPackage\ has been loaded after \Package{backref},
%    as it should be.
%    \begin{macrocode}
\@ifpackageloaded{backref}{%
    \bt@after@brftrue
}{%
    \relax
}       
%    \end{macrocode}
%    \begin{macro}{\bt@citex}
%    \begin{macrocode}
\newcommand\bt@citex{}
\def\bt@citex[#1]#2{%  Add \@extra@b@citeb to \cite
    \let\@citea\@empty
    \@cite{%
        \@for\@citeb:=#2\do{%
            \@citea\let\@citea\citepunct
            \edef\@citeb{\expandafter\@firstofone\@citeb}%
            \if@filesw\immediate\write\@auxout{%
                \string\citation{\@citeb}}\fi
            \@ifundefined{b@\@citeb \@extra@b@citeb}{%
                \mbox{\reset@font\bfseries ?}%
                \@warning{Citation `\@citeb' on page \thepage\space
                undefined}\G@refundefinedtrue
            }{%
                \bt@citesurround{\citeform{\csname b@\@citeb
                \@extra@b@citeb\endcsname}}%
            }%
        }%
    }{#1}%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@nocite}
%    \begin{macrocode}
\newcommand\bt@nocite{}
\def\bt@nocite#1{%
    \@bsphack % Add \@extra@b@citeb to \nocite
    \@for\@citeb:=#1\do{%
        \edef\@citeb{\expandafter\@firstofone\@citeb}%
        \if@filesw
            \immediate\write\@auxout{%
                \string\citation{\@citeb}%
            }%
        \fi
        \@ifundefined{b@\@citeb\@extra@b@citeb}{%
            \G@refundefinedtrue
            \@warning{Citation `\@citeb'  undefined}%
        }{}%
    }%
    \@esphack
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@setcites}
%    A hook to be called by btUnit to activate the redefinitions.
%    We don't call this in any case, since it makes \ThisPackage\
%    incompatible to other packages also defining \Com{@citex}.
%    \begin{macrocode}
\newcommand*\bt@setcites{%
    \let\@citex\bt@citex
    \let\nocite\bt@nocite
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\change@bibcite}
%    Change the \Com{bibcite} command for use with \Env{btUnit}s.
%    \begin{macrocode}
\newcommand\change@bibcite{%
    \let\change@bibcite\relax
    \def\bibcite##1##2{%
        \global\@namedef{b@##1\@extra@binfo}{##2}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\the@ipfilectr}
%    \begin{macro}{\@extra@b@citeb}
%    \begin{macro}{\@extra@binfo}
%    Just as in \Package{chapterbib.sty}.
%    \begin{macrocode}
\gdef\the@ipfilectr{}
\def\@extra@b@citeb{\the@ipfilectr}
\gdef\@extra@binfo{}  % in case .aux files are left from old run.
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \end{macro}

%    Commands to store the original meaning of the \Com{bibitem} commands
%    and of the \Com{begin} and \Com{end} code of \Env{thebibliography}.
%    If natbib isn't loaded, \Com{harvarditem} commands should be treated
%    as errors. We set a flag and give only one error message (via \Com{bt@bibtex@warning}):
%    \begin{macro}{\bt@saveitem}
%    \begin{macro}{\bt@savebib}
%    \begin{macro}{\bt@endsavebib}
%    \begin{macrocode}
\newcommand\bt@saveitem{}
\newcommand*\bt@savebib{}
\newcommand*\bt@endsavebib{}
\newif\ifbt@harvard@errs
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \end{macro}

%    \begin{macro}{\AtBeginDocument}
%    \begin{macrocode}
\AtBeginDocument{%
    \@ifclassloaded{scrbook}{%
        \global\bt@koma@classtrue
    }{%
        \@ifclassloaded{scrartcl}{%
            \global\bt@koma@classtrue
        }{%
            \@ifclassloaded{scrreprt}{%
                \global\bt@koma@classtrue
            }{%
                \relax
            }%
        }%
    }%
    \global\let\bt@savebib\thebibliography
    \global\let\bt@endsavebib\endthebibliography
    \let\bt@saveitem\bibitem
    \@ifpackageloaded{natbib}{%
        \global\bt@natbibtrue
    }{%
        \def\harvarditem{\global\bt@harvard@errstrue}%
        \let\harvardand\relax
        \let\harvardyearleft\relax
        \let\harvardyearright\relax
    }%
%    \end{macrocode}
%    Make sure the loading order of \ThisPackage\ and \Package{backref} is OK:
%    \begin{macrocode}
    \@ifpackageloaded{backref}{%
        \ifthenelse{\not\boolean{bt@after@brf}}{%
            \PackageError{%
                bibtopic%
            }{%
                Load bibtopic after hyperref when using the `backref'
                option\MessageBreak of hyperref%
            }{%
                Please see the section about `Compatibility with other^^J%
                packages' in bibtopic.dvi for details.
            }%
        }{}%
        \global\bt@brftrue
    }{%
        \relax
    }%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\AtEndDocument}
%    Various book-keeping stuff.
%    \begin{macrocode}
\AtEndDocument{%
%    \end{macrocode}
%    The value of \Com{bt@helpctr} (total number of \Com{bibitems} in
%    all bibliographies) is written to the \File{.aux} file; it will
%    be used to compute correct indentation of bibliography items
%    in the next run:
%    \begin{macrocode}
    \immediate\write\@auxout{%
        \string\csname\space bt@set@cnt\string\endcsname{\bt@helpctr}}%
%<*debug>
    \bt@debug{restoring meaning of \string\citation :
        \meaning\@bt@orig@citation}%
%</debug>
    \def\citation#1{\@bt@orig@citation{#1}}%
%    \end{macrocode}
%    \Com{bt@addto@keyval@list} should do nothing when the \File{.aux} file is
%    now read for the second time:
%    \begin{macrocode}
    \let\bt@kv@add\@gobbletwo
%    \end{macrocode}
%    Warn about changed \File{.bbl} files etc.:
%    \begin{macrocode}
    \bt@files@warnings
%    \end{macrocode}
%    Warn in case the numbering (i.\,e. also the widths of
%    the \Com{biblabel}s) has changed:
%    \begin{macrocode}
    \ifnum\bt@helpctr=\bt@totalctr\else
        \PackageWarningNoLine{%
            bibtopic%
        }{%
            Rerun to get indentation of bibitems right%
        }%
    \fi
%<debug>    \bt@debug{total number of items: \bt@helpctr}%
}
%    \end{macrocode}
%    \end{macro}
%
% ^^A --------------------------------------------------
%    \subsubsection{List handling stuff}
% ^^A --------------------------------------------------
%
%    Most of the following commands have been adopted from the \TeX book, p.\,378f.
%    They implement macro-delimited lists (the delimiter being \Com{@elt}) which
%    are more efficient than, say, comma-delimited lists: To check whether a given
%    element is contained in a list, you would have to use iterated macro calls
%    in the latter case, whereas in the former case, the \Com{@elt} macro might
%    be defined to perform the check for its argument, and then
%    the entire list can be executed.
%
%    \begin{macro}{\bt@append@list}
%    Append |#1| to the end of list |#2|. The change is made globally.
%    \begin{macrocode}
\newcommand*\bt@savelist{}
\newcommand*\bt@append@list[2]{%
%<debug>    \bt@debug{appending #1 to #2}%
    \let\bt@savelist#2
%<*debug>
    \bt@debug{list is: #2}%
    \bt@debug{bt@savelist is: \bt@savelist}%
%</debug>
    \protected@xdef#2{\bt@savelist\@elt{#1}}%
%<debug>            \bt@debug{list after append: #2}%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@add@elem}
%    Add |#1| to list |#2|, but only if it's not yet contained in it.
%    \begin{macrocode}
\newcommand*\bt@add@elem[2]{%
    \bt@if@elem{#1}{#2}{%
        \relax
    }{%
        \bt@append@list{#1}{#2}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@testelem}
%    Test if |#1| is contained in list |#2|.
%    \begin{macrocode}
\newcommand\bt@test@cmd{}
\newcommand*\bt@if@elem[2]{%
    \let\bt@test@cmd\@secondoftwo
%    \end{macrocode}
%    Assign |#1| to scratch macro \Com{bt@tempa} (for the \Com{ifx} test).
% ^^A
% ^^A Bug alert: The group was used to keep the changes to \Com{@elt} (used by \LaTeX) and
% ^^A \Com{bt@tempa} local. However this results in problems with the  save stack, so I
% ^^A replaced bt@tempa by bt@tempc and used the \let method instead.
% ^^A
%    \begin{macrocode}
    \let\bt@elt\@elt
%    \begingroup
    \protected@edef\bt@tempc{#1}%
    \def\@elt##1{%
        \protected@edef\bt@tempb{##1}%
        \ifx\bt@tempc\bt@tempb
            \let\bt@test@cmd\@firstoftwo
        \fi
    }%
%    \end{macrocode}
%    Now execute the list:
%    \begin{macrocode}
    #2%
    \let\@elt\bt@elt
%    \endgroup
    \bt@test@cmd
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@mk@warning@list}
%    This will format the list |#1| so that it can be printed nicely in warnings,
%    with each file on a separate line. The result is saved in the token
%    register \Com{@temptokena} (for immediate use).
%    \begin{macrocode}
\newcommand\bt@elt{}
\newcommand*\bt@mk@warning@list[1]{%
    \@temptokena={}%
    \let\bt@elt\@elt
    \def\@elt##1{%
        \@temptokena=\expandafter{\the\@temptokena ##1\MessageBreak}%
    }%
    #1%
    \let\@elt\bt@elt
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bibliographystyle}
%    \begin{macro}{\@orig@bibliographystyle}
%    Redefine \Com{bibliographystyle} to set the global bibliography style
%    (saved in the command name \Com{bt@globalstyle}), to be
%    used by the \Env{btSect} environment. Save original meaning in
%    \Com{@orig@bibliographystyle}.
%    \begin{macrocode}
\newcommand*\@orig@bibliographystyle{}
\let\@orig@bibliographystyle\bibliographystyle
\def\bibliographystyle#1{%
    \gdef\bt@globalstyle{#1}%
    \bt@info{Default bibliographystyle is `#1'}%
    \@orig@bibliographystyle{#1}%
}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%    \begin{macro}{\bibliography}
%    The \Com{bibliography} command isn't used by \ThisPackage, but it
%    was used in the older `\Package{bibtopics}'. This definition just
%    writes an info message to the \File{.log} file.
%    \begin{macrocode}
\def\bibliography{%
    \PackageWarning{%
        bibtopic%
    }{%
        Ignoring `\string\bibliography' command\MessageBreak
        (not compatible with bibtopic.sty)%
    }%
    \@gobble
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\@bt@write@auxfile}
%    Create the additional \File{.aux} files to be read by \BibTeX:
%    |#1| is the argument to \Com{bibstyle},
%    |#2| is the argument to \Com{citation}, and
%    |#3| is the argument to \Com{bibdata}.
%    \begin{macrocode}
\newcommand*\@bt@write@auxfile[3]{%
%    \end{macrocode}
%    So that we can warn the user if an \File{.aux} file has changed,
%    we make a backup of it here.
%    \begin{macrocode}
    \bt@can@overwrite{btaux.aux}%
    \bt@copy@verbatim{\thebtauxfile.aux}{btaux.aux}%    +code:bt@make@backup;
    \immediate\closeout\bt@outfile
%    \end{macrocode}
%     Write new info to \File{.aux} file. If \Package{natbib} is loaded, we add a comment line
%     so that the files are different when switching to/from natbib:
%    \begin{macrocode}
    \immediate\openout\bt@outfile\thebtauxfile.aux
    \ifthenelse{\boolean{bt@natbib}}{%
        \immediate\write\bt@outfile{%
                \@percentchar\@percentchar\space
                Info from `bibtopic.sty': natbib loaded.^^J%
                \string\bibstyle{#1}^^J%
                \string\citation{#2}^^J%
                \string\bibdata{#3}%
        }%
    }{%
        \immediate\write\bt@outfile{%
            \string\bibstyle{#1}^^J%
            \string\citation{#2}^^J%
            \string\bibdata{#3}%
        }%
    }%
    \immediate\closeout\bt@outfile
%    \end{macrocode}
%    Now check if new .aux file and btaux.aux differ, and if so, give a warning,
%    but only if this file hadn't been warned about before (isn't in \Com{bt@warn@files}).
%    \begin{macrocode}
    \bt@if@files@differ{\thebtauxfile.aux}{btaux.aux}{%
        \bt@if@elem{\thebtauxfile}{\bt@warn@files}{%
            \relax
        }{%
            \ifthenelse{\boolean{bt@normalwarnings}}{%
                \PackageWarningNoLine{%
                    bibtopic%
                }{%
                    \thebtauxfile.bbl may be outdated%
                }%
            }{%
                \bt@appendtofile{\thebtauxfile.bbl}{%
                    \string\csname\space
                    bt@warn@outdated\string\endcsname{\thebtauxfile}%
                }%
            }%
        }%
    }{}% they don't differ
}

%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@appendtofile}
%    Append |#2| to file |#1|. This is more complicated than one would
%    like it to be: We need to copy the file to a tmp file (\File{btbbl.aux})
%    and then back to the file, but this time \emph{without} closing
%    the filehandle, so that subsequent \Com{write}s to the file will
%    append to the file (rather than overwrite the contents).
%    (\Com{bt@closeout} closes the handle \Com{bt@outfile}, which is
%    always the file currently written to).
%    \begin{macrocode}
\newcommand*\bt@appendtofile[2]{%
    \bt@can@overwrite{btbbl.aux}%
    \bt@copy@verbatim{#1}{btbbl.aux}%
    \immediate\closeout\bt@outfile
    \bt@copy@verbatim{btbbl.aux}{#1}
    \immediate\write\bt@outfile{\expandafter\string #2}%
    \immediate\closeout\bt@outfile
}
%    \end{macrocode}
%    \end{macro}

%
%   The following two commands are written to the \File{.aux} file by the
%   \Env{btUnit} environment to handle different citation lists correctly.
%
%    \begin{macro}{\bt@save@list}
%    Save \Com{bt@cited@list} by writing it to \Com{bt@sect}|#1|, where |#1| is
%    the current number of the \Env{btUnit} (\Com{bt@unit@cnt}).
%    \begin{macrocode}
\newcommand*\bt@save@list[1]{%
    \expandafter\protected@xdef\csname bt@sect%
       #1\endcsname{\bt@cited@list}%
%<*debug>
       \bt@debug{saving list #1\space is:
            \csname bt@sect#1\endcsname}%
%</debug>
}
%    \end{macrocode}
%    \end{macro}
%
% ^^A --------------------------------------------------
%    \subsubsection[\texttt{thebibliography}; parsing the \texttt{bibitem} commands]{Redefinition of
%       \Env{thebibliography}\\ and parsing the \Com{bibitem} commands}
% ^^A --------------------------------------------------
%    
%    We'd like to be able to print only selected \Com{bibitem}s (e.\,g., those cited, or
%    those not cited). To select these, we make the \Com{bibitem} command fake an environment
%    that contains the entire item, so that it's easy to ignore its contents entirely.
%    That is, a \Env{thebibliography} environment like the following:
%    \begin{verbatim}
%    \begin{thebibliography}{10}
%    \bibitem[a] foo
%    \bibitem[b] bar
%    \bibitem[c] roo
%    \end{thebibliography}
%    \end{verbatim}
%    shall expand to:
%    \begin{verbatim}
%    \begin{thebibliography}{10}
%    \begin{myitem}[]
%    \end{myitem}
%    \begin{myitem}[a]
%    foo
%    \end{myitem}
%    \begin{myitem}[b]
%    bar
%    \end{myitem}
%    \begin{myitem}[c]
%    roo
%    \end{myitem}
%    \begin{myitem}[]
%    \end{myitem}
%    \end{thebibliography}
%    \end{verbatim}
% ^^A   
%    Note the empty \Env{myitem} environments after
%    \BTbegEnv{thebibliography} and before
%    \BTendEnv{thebibliography}, respectively: These are needed since
%    \Com{bibitem}\oarg{arg} is defined as
%    \BTendEnv{myitem}\BTbegEnv{myitem}\oarg{arg}.^^A
%    \footnote{Yes, this \emph{is} strange, but it seems to work -- contrary to
%    the other schemes I tried before (looking for certain characters
%    in the input, reading over stuff etc.) If you have a better idea,
%    please \emph{do} tell me about it!}
%    The missing \BTbegEnv{myitem} will be inserted by the
%    redefined \BTbegEnv{thebibliography} just after
%    the usual \Com{begin} code, and the missing \BTendEnv{myitem}
%    will be inserted by \BTendEnv{thebibliography}. (This is actually the
%    reason why we need to redefine \Env{thebibliography}).
%
%    \begin{macro}{\btBegThbCmd}
%    A hook for inserting commands between the \BTbegEnv{thebibliography}
%    command and the first \Com{bibitem}. Currently unused.
%    \begin{macrocode}
\newcommand\btBegThbCmd{}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@beg@thb@hook}
%    We call the \Env{bt@item} environment here (and anywhere else)
%    in plain-\TeX\ fashion so that its contents are not inside a group.
%    This is important in case there are definitions after
%    \BTbegEnv{thebibliography}, which otherwise wouldn't work.
%    It also should reduce the general overhead.
%    \begin{macrocode}
\newcommand*\bt@beg@thb@hook{%
    \btBegThbCmd
    \global\bt@found@itemfalse
    \bt@item{}%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@end@thb@hook}
%    \changes{v1.0i}{2000/10/09}{%
%       \Package{jurabib} compatibility: Replaced \chCom{theenumiv} by
%       \chCom{@arabic}\chCom{c@enumiv} to fix a bug with \Package{jurabib}'s
%       definition of \chEnv{thebibliography}: it doesn't redefine
%       \chCom{theenumiv}, so \chCom{theenumiv} is still defined as
%       \chCom{@Alph}\chCom{c@enumiv}, expanding to `' for 0 and causing
%       an error later
%    }
%    \begin{macrocode}
\newcommand\bt@save@cnt{0}
\newcommand*\bt@end@thb@hook{%
    \endbt@item
    \ifthenelse{\boolean{bt@natbib}}{%
        \protected@xdef\bt@save@cnt{\theNAT@ctr}%
    }{%
        \protected@xdef\bt@save@cnt{\@arabic\c@enumiv}%
    }%
    \bt@bibitemcheck
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@change@bibitem}
%    This command is called from the \Com{btPrint...}
%    commands; it changes the \Com{harvarditem} and \Com{bibitem} commands to
%    call our `fake' environments that do the optional printing of the
%    bibitems.
%    \begin{macrocode}
\newcommand*\bt@change@bibitem{%
    \expandafter\ifx\btBegThbCmd\empty\else
            \bt@info{\string\btBegThbCmd nonempty: \meaning\btBegThbCmd}%
    \fi
%    \end{macrocode}
%    \changes{v0.1}{1999/09/20}{%
%       Added reset to switch \chCom{@bt@found@item@}
%    }
%    The switch \Com{@bt@found@item@} is set to false again for the start of
%    a new bibliography.
%    \begin{macrocode}
    \ifthenelse{\boolean{bt@natbib}}{%
        \def\harvarditem{\endbt@item\bt@harvitem}%
    }{}%
    \def\bibitem{\endbt@item\bt@item}%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\bt@adjust@label}
%    Set up the space needed for the bibliography labels.^^A
%    \footnote{^^A
%    The required space can't be simply calculated from the first argument
%    of \Env{thebibliography}: with \File{plain.bst} this argument (if numerical)
%    just contains a symbolic representation $x$ for the width of the numerical labels,
%    computed as follows (see the function \Env{longest.label.pass} in \File{plain.bst}):
%    $x = 10^n$, where $n = {}${\itshape stringlen} ({\itshape
%    number of the last item})${} - 1$.
%    (So, for example, $x = 1$ for a bibliography containing less than 10 items,
%    and $x = 10$ for a bibliography containing less than 100 labels. Annoying, isn't it?)}
%    ^^A
%    The maximal number of \Com{bibitems} is contained in the counter
%    \Com{bt@totalctr} (read from the \File{.aux} file from the previous
%    run); we use it to set the value for the indentation of \emph{all} item labels.
%   ^^A
%    \begin{macrocode}
\newcommand*\bt@adjust@label[1]{%     +code:bt@adjust@label;
    \bt@isnum{#1}{%
        \def\bt@label{\bt@totalctr}%
    }{%
        \def\bt@label{#1}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@change@thb}
%    The following command for changing \Env{thebibliography}
%    was adopted from the \Com{sectionbib} command
%    in \Package{chapterbib.sty} (D. Arseneau).
%    Its main purposes are:
%   ^^A
%    \begin{itemize}
%    \item
%       (optionally) remove the headings from \Env{thebibliography}
%       (user will set his own with the ordinary sectioning commands),
%    \item
%       (optionally) remove the reset of the bibitem counter for numerical citation styles,
%    \item
%       call the \Com{bt@item} command immediately after opening \Com{thebibliography},
%       and the \Com{endbt@item} command before closing \Com{thebibliography}.
%       This might be requested only conditionally (wouldn't need it for \Com{btPrintAll}
%       -- currenlty it's just always used), so we use the hooks
%       \Com{bt@beg@thb@hook} and \Com{bt@end@thb@hook} that are set up 
%       by calling \Com{bt@change@bibitem}.
%    \end{itemize}
%    We check what kind of \Env{thebibliography} environment we're dealing with, and
%    call the appropriate command to do the changes: \Com{bt@mydochangechange@nat@thb},
%    \Com{bt@change@default@thb} or \Com{bt@change@KOMA@thb}.
%   ^^A
%    \begin{macrocode}
\newcommand*\bt@change@thb{%
    \long\def\bt@tempa##1##2\endthebibliography{%
        \def\bt@tempc{##1}%
    }%
    \expandafter\bt@tempa\thebibliography{}\endthebibliography
%    \end{macrocode}
%    With the \Package{backref} package, \Com{thebibliography} is overloaded
%    to start with \Com{@starttoc}, and we have to look at
%    the redefined command instead. The original command is saved by
%    \Package{backref} either as \Com{oldbibl}
%    (for versions $\leq$ 1.16 from 1999/04/12) or as \Com{BRorg@thebibliography}
%    (for version 1.19 from 2000/01/19).
%    \begin{macrocode}
    \ifthenelse{\boolean{bt@brf}}{%
        \@ifundefined{BRorg@thebibliography}{%
            \PackageInfo{bibtopic}{assuming backref.sty <= v1.16}%
            \let\bt@brf@bbl@cmd\oldbibl
        }{%
            \PackageInfo{bibtopic}{assuming backref.sty >= v1.19}%
            \let\bt@brf@bbl@cmd\BRorg@thebibliography
        }%
        \def\bt@tempb{\@starttoc}%
        \ifx\bt@tempb\bt@tempc
            \expandafter\bt@tempa\bt@brf@bbl@cmd{}\endthebibliography
        \fi
    }{}%
%    \end{macrocode}
%    If a {\scshape KOMA}-class is loaded, the first command in
%    \Env{thebibliography} is \Com{bib@heading}; for \Package{natbib} v6.x
%    it's \Com{bibfont}, for \Package{natbib} v7 it's \Com{bibsection}.
%    KOMA versions ${}\geq 2.9$ are dealt with below.
%    \begin{macrocode}
    \def\bt@tempa{\bibfont}%
    \ifx\bt@tempa\bt@tempc %
%<debug>        \bt@debug{assuming natbib v6.x-style thb env}%
        \bt@change@nat@thb
    \else
        \def\bt@tempa{\bibsection}%
        \ifx\bt@tempa\bt@tempc
%<debug>        \bt@debug{assuming natbib v7-style thb env}%
            \bt@change@nat@thb
        \else
            \def\bt@tempa{\bib@heading}%
            \ifx\bt@tempa\bt@tempc
%<debug>            \bt@debug{assuming older KOMA-style thb env}%
                \bt@change@KOMA@thb
%    \end{macrocode}
%    Check if the definition from the standard classes is used. This begins
%    with either \Com{section} (for \Env{article}) or \Com{chapter} (for \Env{report}
%    or \Env{book}).
%    \begin{macrocode}
            \else
                \def\bt@tempa{\chapter}%
                \ifx\bt@tempa\bt@tempc
%<debug>                    \bt@debug{assuming book thb env}%
                    \bt@change@standard@thb
                \else
                    \def\bt@tempa{\section}%
                    \ifx\bt@tempa\bt@tempc
%<debug>                        \bt@debug{assuming article thb env}%
                    \bt@change@standard@thb
                    \else
%    \end{macrocode}
%    With newer KOMA versions, \Com{bib@heading} is not at the beginning of
%    \Com{thebibliography}; but for these we can assume that \Com{bib@heading}
%    will be available, so \Com{bt@change@KOMA@thb} should work.
%    \begin{macrocode}
                        \ifbt@koma@class
%<debug>                    \bt@debug{assuming newer KOMA-style thb env}%
                            \bt@change@KOMA@thb
                        \else
%    \end{macrocode}
%    Nothing appropriate at all; either use the fallback definition if
%    \Env{defaultbib} option has been specified, or complain:                   
%    \begin{macrocode}
                            \ifthenelse{\boolean{bt@fallback@thb}}{%
                                \PackageWarning{%
                                    bibtopic%
                                }{%
                                    `defaultbib' specified; using
                                    built-in\MessageBreak
                                    `thebibliography' environment%
                                }%
                                \let\thebibliography\bt@dflt@bthb
                                \let\endthebibliography\bt@dflt@ethb
                            }{%
                                \PackageError{%
                                    bibtopic%
                                }{%
                                    Found unknown `thebibliography' environment%
                                }{%
                                    You should either use a package providing
                                    a known bibliography^^J%
                                    environment (such as natbib), or use the
                                    `defaultbib' package^^J%
                                    option as a workaround; please see the
                                    section about `Warnings^^J%
                                    and error messages' in `bibtopic.dvi' for
                                    details.
                                }%
                            }%
                        \fi
                    \fi
                \fi
            \fi
        \fi
    \fi
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@dflt@bthb}
%    When the \Env{defaultbib} option is specified, this definition is used
%    instead of an incompatible definition of \Env{thebibliography}.
%    It is similar to the definition found in the \textsc{KOMA} classes.
%    \begin{macrocode}
\providecommand\@openbib@code{}
\newcommand\bt@dflt@bthb[1]{%
    \bt@adjust@label{#1}%
    \ifthenelse{\boolean{bt@printheadings}}{%
        \@ifundefined{chapter}{%
            \@ifundefined{section}{%
%    \end{macrocode}
%    Use the \LaTeX2e kernel command directly to print a section heading -- this works only
%    because the \Env{section}-related stuff (\Com{thesection}, \Com{l@section}, which
%    needn't be defined for any documentclass) isn't called for the |*|-form.
%    \begin{macrocode}
            \@startsection{section}{1}{\z@}%
                {-3.5ex \@plus -1ex \@minus -.2ex}%
                {2.3ex \@plus.2ex}%
                {\normalfont\Large\bfseries}*{\refname}%
            }{%
            \section*{\refname\@mkboth{\refname}{\refname}}%
            }%
        }{%
            \chapter*{\bibname\@mkboth{\bibname}{\bibname}}%
        }%
    }{}%
    \list{\@biblabel{\@arabic\c@enumiv}}{%
        \settowidth\labelwidth{\@biblabel{#1}}%
        \leftmargin\labelwidth
        \advance\leftmargin\labelsep
        \@openbib@code
        \ifthenelse{\boolean{bt@sectctr@reset}}{%
            \usecounter{enumiv}%
        }{%
            \@nmbrlisttrue
            \def\@listctr{enumiv}%
        }%
        \let\p@enumiv\@empty
        \renewcommand*\theenumiv{\@arabic\c@enumiv}%
    }%
    \sloppy\clubpenalty4000\widowpenalty4000%
    \sfcode`\.=\@m
    \bt@beg@thb@hook
}%
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@dflt@ethb}
%    Fallback code for the end of the environment:
%    \begin{macrocode}
\newcommand\bt@dflt@ethb{%
    \bt@end@thb@hook
    \def\@noitemerr{%
        \@latex@warning{Empty `thebibliography' environment}%
    }%
    \endlist
}%
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@change@nat@thb}
%    Change the definition of the \Package{natbib}
%    \Env{thebibliography} definition. We call our adjusting macro for
%    the label width, and optionally disable \Com{setcounter} to get continuous
%    numbering and the \Package{natbib} hook \Com{bibsection}.
%    \begin{macrocode}
\newcommand\bt@change@nat@thb{%
%<debug>    \bt@debug{Changing natbib-style thebibliography}%
    \def\thebibliography##1{%
        \bt@adjust@label{##1}%
        \ifthenelse{\not\boolean{bt@printheadings}}{%
            \let\bibsection\relax
        }{}%
%    \end{macrocode}
%    Call the original \BTbegEnv{thebibliography} command:
%    \begin{macrocode}
        \bt@savebib{\bt@label}%    +code:bt@thb@headings;
        \ifthenelse{\not\boolean{bt@sectctr@reset}}{%
            \setcounter{NAT@ctr}{\bt@save@cnt}%
        }{}%
        \bt@beg@thb@hook
    }%
%    \end{macrocode}
%    Similarly for the original \BTendEnv{thebibliography} command:
%    \Com{bt@end@thb@hook} calls \Com{endbt@item}. We \emph{don't} call
%    \Com{bt@endsavebib} here, but overwrite the \Package{natbib}
%    \Com{endthebibliography} definition
%    explicitly: it adds a \Com{vskip}-\Com{lastskip} after the \Com{endlist}, which
%    produces differently (horribly) looking results if natbib is loaded before
%    \ThisPackage; I guess this would be buggy behaviour.
%    \begin{macrocode}
    \def\endthebibliography{%
       \bt@end@thb@hook
       %   \bt@endsavebib %% not; define it explicitly instead:
       \def\@noitemerr{%
           \PackageWarning{%
              bibtopic%
           }{%
              Empty `thebibliography' environment%
           }%
       }%
       \endlist % \vskip-\lastskip omitted here
    }%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@change@standard@thb}
%    The standard classes' \Env{thebibliography}. Most of the
%    commands are similar to the \Package{natbib} case before, with the
%    exception that we disable \Com{usecounter} instead of \Com{setcounter}
%    unless the option \Env{sectcntreset} has been used.
%    \begin{macrocode}
\newcommand*\bt@change@standard@thb{%
    \def\thebibliography##1{%
        \bt@adjust@label{##1}%
        \ifthenelse{\not\boolean{bt@printheadings}}{%
%    \end{macrocode}
%    These \Com{let}s are local to the current definition:
%    \begin{macrocode}
            \let\chapter\@gobbletwo
            \let\section\@gobbletwo
        }{}%
        \bt@savebib{\bt@label}%
        \ifthenelse{\not\boolean{bt@sectctr@reset}}{%
            \setcounter{enumiv}{\bt@save@cnt}%
        }{}%
        \bt@beg@thb@hook
    }%
    \def\endthebibliography{%
        \bt@end@thb@hook
        \bt@endsavebib
    }%
}      
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@change@KOMA@thb}
%    To remove the headings from a \textsc{KOMA}
%    \Env{thebibliography}, we disable \textsc{KOMA}'s hook
%    \Com{bib@heading}. Then we call the default procedure
%    \Com{bt@change@standard@thb}. (TODO: Should KOMA's \Com{bibpreamble}
%    be preserved? The usual way with \Package{bibtopic} is to specify headers
%    and additional text in-line. The only problem is that the text is
%    ignored, and users may not realize that.)
%    \begin{macrocode}
\newcommand*\bt@change@KOMA@thb{%
    \ifthenelse{\not\boolean{bt@printheadings}}{%
        \let\bib@heading\relax
    }{}%
    \bt@change@standard@thb
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@harvitem}
%    Replacement for \Com{harvarditem} (set up by \Com{bt@change@bibitem}).
%    \begin{macrocode}
\newcommand\bt@harvitem{%
    \@ifnextchar[{\bt@@harvitem}{\bt@@harvitem[]}%] brace matching
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@@harvitem}
%    \Package{natbib} maps the arguments of \Com{harvarditem} to the optional
%    argument of \Com{bibitem}, inserting braces as separators.
%    We just do the same here. (I guess that we could also
%    check for the presence of the unchanged definition of \Com{harvarditem},
%    as for \Env{thebibliography} just before. But would it be worth it?).
%    \begin{macrocode}
\newcommand*\bt@@harvitem[4][]{%
%<debug>    \bt@debug{btharvitem called with args: |#1|#2|#3|#4|}%
    \ifthenelse{\equal{#1}{}}{%
        \protected@xdef\bt@args{[#2(#3)]}%
    }{%
        \bt@warn@brackets{#2}#1[]\end%
        \protected@xdef\bt@args{[#1(#3)#2]}%
    }%
    \bt@call@item{#4}%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{environment}{bt@item}
%    Replacement for \Com{bibitem}.
%    \begin{macrocode}
\newenvironment{bt@item}{%
    \@ifnextchar[{\bt@@item}{\bt@@item[]}%] brace matching
}{
    \relax
}
%    \end{macrocode}
%    \end{environment}
%    \begin{macro}{\bt@@item}
%    Do some argument checking: if the optional argument is numerical,
%    it will most probably mess up our own continuous numbering,
%    so we ignore this number and give a warning. This behaviour
%    can be customized by the options \Env{overridenumbers} and \Env{dontoverridenumbers}
%    which set the switches \Env{@bt@override@numargs@} and \Env{@bt@warn@override@}
%    appropriately (see there).
%    At the end we call the original commands with the arguments (the
%    optional argument is in \Com{bt@args}).
%    \changes{v1.0a}{1999/07/06}{%
%          Replaced \chCom{edef} here and
%          in other places by \chCom{protected@edef}
%    }
%    \begin{macrocode}
\newcommand*\bt@@item[2][]{%
    \ifthenelse{\equal{#2}{}}{%
%    \end{macrocode}
%    In this case, the current item is one of the `dummy' items at the
%    beginning or end of \Env{thebibliography}. We do nothing in this case
%    (don't call \Com{bt@call@item}, so that commands eventually occurring
%    at this place are still executed etc.).
%    \begin{macrocode}
        \def\endbt@item{\relax}%
    }{%
        \ifthenelse{\equal{#1}{}}{%
            \gdef\bt@args{}%
        }{%
            \bt@isnum{#1}{%
                \ifthenelse{\boolean{bt@override@numargs}}{%   
                    \global\bt@overridden@numargstrue
                    \gdef\bt@args{}%
                }{%
                    \bt@warn@brackets{#2}#1[]\end%
                    \protected@xdef\bt@args{[#1]}%
                }%
            }{%
                \bt@warn@brackets{#2}#1[]\end%
                \protected@xdef\bt@args{[#1]}%
            }%
        }%
        \bt@call@item{#2}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@warn@brackets}
%    Warn user if brackets inside the argument of the \Com{bt@@item} command might
%    confuse \Com{bt@call@item}. This might happen with keys in the \File{.bbl}
%    file looking like this: ``\File{key = \Obr[FOO]\Cbr}''. Such keys should be enclosed into
%    another pair of braces to protect them.
%    \begin{macrocode}
\newcommand*\bt@warn@brackets{}
\def\bt@warn@brackets#1#2[#3]#4\end{%
    \ifthenelse{\equal{#3}{}}{%
        \relax
    }{%
        \PackageError{%
            bibtopic%
        }{%
            Can't parse brackets in key `#1' properly%
        }{%
            You seem to have used brackets `[]' inside that key in^^J%
            `\bt@curr@bib@file.bib', and bibtopic could have confused these^^J%
            with the optional argument of the `\string\bibitem' command.^^J%
            To avoid this, please `hide' such brackets in an extra pair^^J%
            of braces, like this: `{[]}'.^^J^^J%
            (Don't forget to rerun BibTeX on `\thebtauxfile' afterwards.)^^J%
            If you proceed now, your bibliograpy may look somewhat garbled.
        }%
    }%
}
%    \end{macrocode}
%    \end{macro}

%
%    \begin{macro}{\bt@boxing@hook}
%    \changes{v1.0d}{2000/06/17}{%
%       Added this hook
%    }
%    \changes{v1.0i}{2000/10/09}{%
%       \Package{jurabib} compatibility: Added \chCom{jbdoitem} and \chCom{jbbibargs}
%       to \chCom{bt@boxing@hook}
%    }
%    The following hook disables `dangerous' commands that could
%    cause side-effects inside a \Com{bibitem} that should be
%    skipped. For example, some styles insert a \Env{quotation}
%    environment for comments, causing a \Com{@noitemerr} in this
%    case. (I guess this shows that the method with the \Env{lrbox}
%    isn't really bullet-proof, since it only prevents typesetting,
%    but not exection of commands. Is there a better way to implement
%    this?) The hook is called inside an \Env{lrbox} environment, so
%    all redefinitions are local to that environment.
%    \begin{macrocode}
\newcommand*\bt@boxing@hook{%
    \global\let\@noitemerr\relax
%    \end{macrocode}
%    Disable all citation commands that might occur as cross references in
%    entries we want to ignore.
%    \begin{macrocode}
    \def\cite{%
        \@ifstar{}{}% just gobble it
        \@ifnextchar[{% brace matching ]}{
            \@citex
        }{%
            \@citex[]%
        }%
    }
    \def\@citex[##1]{%
        \@ifnextchar[{%]}{
            \bt@gobble@citex[##1]%
        }{%
            \bt@gobble@citex[##1][]%
        }%
    }%
    \def\bt@gobble@citex[##1][##2]##3{}%
%    \end{macrocode}
%    Most of these are from \Package{natbib.sty}.
%    \begin{macrocode}
    \let\citet\cite
    \let\Citet\cite
    \let\citep\cite
    \let\Citep\cite
    \let\citealt\cite   
    \let\Citealt\cite
    \let\citealp\cite
    \let\Citealp\cite
    \let\citetext\cite
    \let\citeauthor\cite
    \let\Citeauthor\cite
    \let\citeauthoryear\cite
    \let\citeyearpar\cite
    \let\citetalias\cite
    \let\citepalias\cite
%    \end{macrocode}
%    \Package{jurabib} typesets a bibitem by calling these commands:
%    \begin{macrocode}
    \let\jbdoitem\relax
    \let\jbbibargs\bt@gobblethree
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@call@item}
%    This command does the real `hard work': it checks if the current item had been
%    cited or not (using \Com{bt@testelem}) and takes the appropriate actions
%    according on the value of the booleans \Env{@bt@print@$\{$positive$\mid$all$\}$@}:
%    \begin{itemize}
%    \item print the item, in which case we do next to nothing (only keyval and bookkeeping
%          stuff);
%    \item don't print the item: In this case, we put the entire item into a \Env{lrbox}
%          that we just won't use any more; i.\,e. we throw it away. There may
%          be more efficient/elegant ways to do this, but `scanning over it'-schemes
%          would not work since the \Com{end} code of these items isn't standing
%          verbatim in the input (but only the next \Com{bibitem} command that will
%          expand to it).
%    \end{itemize}
%    Again, we differentiate a `fast' and a `slow' case
%    (the cases where items should be printed are just reversed).
%    \begin{macrocode}
\newcommand*\bt@call@item{}
\ifthenelse{\boolean{bt@fast}}{%
   \def\bt@call@item#1{%
%<debug>       \bt@debug{bt@call@item called with arg: |#1|}%
       \@ifundefined{#1bt@\@extra@b@citeb}{%
           \bt@print@all@or@notcited{#1}%
       }{%
           \bt@print@all@or@cited{#1}%
       }%
   }
}{%
%    \end{macrocode}
%    The `slow' case. Instead of the internal table of command names,
%    we make the lookup in our list of cited items. Except for this
%    (and the fact that the positive\slash nonpositive cases are inversed)
%    there's not much difference to the above.
%    \begin{macrocode}
   \def\bt@call@item#1{%
%<debug>       \bt@debug{bt@call@item called with arg: |#1|}%
       \def\endbt@item{\relax}%
       \bt@if@elem{#1}{\csname bt@sect\bt@unit@cnt\endcsname}{%
           \bt@print@all@or@cited{#1}%
       }{%
           \bt@print@all@or@notcited{#1}%
       }%
   }%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@print@all@or@cited}
%    This macro prints all items or those actually cited.
%    \begin{macrocode}
\newcommand*\bt@print@all@or@cited[1]{%
    \ifthenelse{\boolean{bt@print@cited}}{%
        \bt@do@print@item{#1}%
    }{%
        \ifthenelse{\boolean{bt@print@all}}{%
            \bt@do@print@item{#1}%
        }{%
            \bt@dont@print@item
        }%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@print@all@or@notcited}
%    This macro prints all items or those not cited.
%    \begin{macrocode}
\newcommand*\bt@print@all@or@notcited[1]{%
    \ifthenelse{\boolean{bt@print@cited}}{%
%<*debug>
        \bt@debug{printing cited: #1}%
%</debug>
        \bt@dont@print@item
    }{%
        \bt@do@print@item{#1}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@do@print@item}
%    Actually prints the item.
%    \begin{macrocode}
\newcommand*\bt@do@print@item[1]{%
    \global\bt@found@itemtrue
    \bt@stepcnt\bt@helpctr
    \bt@if@elem{#1}{\bt@kv@req@list}{%
        \bt@add@elem{#1}{\bt@sect@ref@list}%    +code:bt@sect@ref@listAdd;
    }{}%
    \def\endbt@item{\relax}%
    \expandafter\bt@saveitem\bt@args{#1}%
}

\newbox\bt@tempboxa

\newcommand*\bt@dont@print@item{%
    \def\endbt@item{%
        \end{lrbox}%
    }%
    \begin{lrbox}{\bt@tempboxa}%
    \bt@boxing@hook
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\bt@copy@verbatim}
%    Copy |#1| to |#2|. |#2| isn't closed, so
%    subsequent \Com{write}s to |#2| can be used to append lines to |#2|.
%    \begin{macrocode}
\newcommand\bt@copy@verbatim[2]{%
%       \PackageInfo{bibtopic}{Making backup of #1 ...}%
    \openin\bt@infilea=#1\relax
    \immediate\openout\bt@outfile=#2\relax
%    \end{macrocode}
%    Write our signature to the file:
%    \begin{macrocode}
    \immediate\write\bt@outfile{%
        \@percentchar%
        \@percentchar%
        \@percentchar%
        \space produced automatically by bibtopic.sty v1.0k%
    }%
    \begingroup
        \let\do\@makeother \dospecials
        \endlinechar\m@ne
        \ifeof\bt@infilea
            \bt@info{Tried to copy #1, but couldn't find it}%
        \else
            \loop
                \read\bt@infilea to\bt@tempa
%<debug>                \bt@debug{LINE: \bt@tempa}%
                % same trick as with \if!...!
                \if\ifeof\bt@infilea 0\else 1\fi 1
                \immediate\write\bt@outfile{\bt@tempa}%
            \repeat
        \fi
    \endgroup
%    \end{macrocode}
%    Closing \Com{bt@outfile} is done optionally in the calling macro
%    (to make it possible to append stuff).
%    \begin{macrocode}
    \closein\bt@infilea
}
%    \end{macrocode}
%    \end{macro}
%    
%    \begin{macro}{\bt@can@overwrite}
%    Check if we can overwrite |#1|, i.e. if it is a file produced by
%    \ThisPackage. This is veryfied by checking if the first line of
%    the file is a `signature' line of the following form:\medskip
%
%    \noindent{\footnotesize\begin{tabular}{@{}l}
%    \verb|%%% produced automatically by bibtopic.sty v|^^A
%        $\langle$major-version$\rangle$|.|$\langle$minor-version$\rangle$
%    \end{tabular}}
%
%    \begin{macrocode}
\newcommand*\bt@can@overwrite[1]{%
    \openin\bt@infilea=#1\relax
    \bgroup
        \let\do\@makeother \dospecials
        \endlinechar\m@ne
        \ifeof\bt@infilea
            \bt@info{File `#1' doesn't exist}%
        \else
            \read\bt@infilea to\@tempa
            \ifeof\bt@infilea
                \bt@info{File `#1' is empty}%
            \else
            \bt@if@signatureline{\@tempa}{%
                \relax
            }{%
                \PackageError{bibtopic}{%
                    file `#1' not written by bibtopic%
                }{%
                    The file `#1' looks as if it hasn't been written
                    by bibtopic;^^J%
                    however, bibtopic would now try to overwrite this file.^^J%
                    (See section 3 in bibtopic.dvi for more details.)^^J%
                    If this file contains anything important, please^^J%
                    copy its contents to a safe place now.^^J^^J%
                    If you hit RETURN now, this file will be overwritten.^^J%
                }%
            }%
            \fi
        \fi
    \egroup
    \closein\bt@infilea
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@if@signatureline}
%    \begin{macro}{\bt@if@@signatureline}
%    Checks if the argument starts with a signature line of the format described
%    for \Com{bt@can@overwrite} above. `\verb|%|' and `\verb*| |' are \Com{catcode}d
%    to `other' to match the catcodes in the line just read, and
%    \Com{endlinechar} is unset for convenience (so that we don't need to
%    uncomment line endings). The version is extracted and written to
%    \Com{bt@version}, even if we don't use it currently.
%    \begin{macrocode}
\newcommand\bt@version{0}
\newcommand\bt@if@@signatureline{}
\newcommand\bt@if@signatureline{}
{
%    \end{macrocode}
%    This group is used to keep the \Com{catcode} changes local.    
%    \begin{macrocode}
\catcode`\ =12
%    \end{macrocode}
%    Note: no spaces from here on. Use \Com{endlinechar}\Com{m@ne}
%    so that line endings needn't be escaped (`\%' couldn't be used for that).
%    \begin{macrocode}
\catcode`\%=12
\endlinechar\m@ne
\gdef\bt@if@signatureline#1{
\expandafter\bt@if@@signatureline
#1%%% produced automatically by bibtopic.sty v.%%%\end
}
\gdef\bt@if@@signatureline
#1%%% produced automatically by bibtopic.sty v#2.#3%%%#4\end{
\ifx\\#2\\
\let\bt@tempc\@secondoftwo
\else
\def\bt@version{#2.#3}
\let\bt@tempc\@firstoftwo
\fi
\bt@tempc
}
}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}

%    \begin{macro}{\bt@if@files@differ}
%    Execute |#3| if the files |#1| and |#2| differ,
%    |#4| if they don't differ.
%    \changes{v1.0j}{2000/10/17}{%
%        Replaced \chCom{@firstofone}, \chCom{@firstoftwo} at end by
%        additional args (babel\slash \chCom{ifthenelse} bug)
%    }
%    \begin{macrocode}
\newif\ifbt@cont
\newif\ifbt@files@diff
\newcommand\bt@line@cnt{}
\newcommand*\bt@if@files@differ[4]{%    +code:bt@if@files@differ;
%<debug>    \bt@debug{comparing #1.aux - #1.bak ...}%
    \bt@files@difffalse
    \def\bt@line@cnt{0}%
    \bgroup
        \let\do\@makeother
        \dospecials
        \endlinechar-1
        \openin\bt@infilea=#1
        \openin\bt@infileb=#2
%    \end{macrocode}
%    Set continuation flag to \emph{true}, and enter reading loop.
%    \begin{macrocode}
        \bt@conttrue
        \loop
%    \end{macrocode}
%    This catches the normal termination case and also the case
%    where one of the files doesn't exist or is empty
%    (at EOF just after opening it):
%    \begin{macrocode}
        \ifeof\bt@infilea
%<debug>            \bt@debug{EOF #1}%
            \bt@contfalse
            \ifeof\bt@infileb
%<debug>                \bt@debug{EOF #2}%
            \else
%    \end{macrocode}
%    At EOF at file $a$, but not at EOF at file $b$: files are different.
%    \begin{macrocode}
%<debug>                \bt@debug{NOT at EOF #1.bak, but EOF #1.aux}%
                \global\bt@files@difftrue
            \fi
        \else
            \ifeof\bt@infileb
%    \end{macrocode}
%    At EOF at file $b$, but not at EOF at file $a$:
%    \begin{macrocode}
%<debug>                \bt@debug{EOF #1.bak}%
                \bt@contfalse
                \global\bt@files@difftrue
            \fi
        \fi
%    \end{macrocode}
%    Not at EOF; read the lines to scratch macros \Com{bt@tempa} and \Com{bt@tempb}:
%    \begin{macrocode}
        \ifbt@cont
%<debug>            \bt@debug{NOT at EOF of both.}%
            \read\bt@infilea to\bt@tempa
            \read\bt@infileb to\bt@tempb
%    \end{macrocode}
%    first line in file |#2| might be signature line; skip over it (file |#1| doesn't have
%    such a line):          
%    \begin{macrocode}
            \bt@stepcnt{\bt@line@cnt}%
            \ifnum\bt@line@cnt=1
                \bt@if@signatureline{\bt@tempb}{%
                    \read\bt@infileb to\bt@tempb
                }{}%
            \fi
%    \end{macrocode}
%    Test if the two lines just read are equal, and re-enter the loop:
%    \begin{macrocode}
            \ifx\bt@tempa\bt@tempb
%<debug>                \bt@debug{\bt@tempa -\bt@tempb\space are equal}%
            \else
%<*debug>
                \bt@debug{|\bt@tempa| - |\bt@tempb| differ!}%
%</debug>
                \bt@contfalse
                \global\bt@files@difftrue
            \fi
        \repeat
%    \end{macrocode}
%    Done with the comparison loop; close the files, close enclosing
%    group and
%    print result of the comparison (i.\,e., a warning message
%    if the files differ):
%    \begin{macrocode}
        \closein\bt@infilea
        \closein\bt@infileb
    \egroup
    \ifthenelse{\boolean{bt@files@diff}}{%
        #3%
    }{%
        #4%
    }%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@set@cnt}
%    This command will be read from the \File{.aux} file; it sets
%    \Com{bt@totalctr} (used by \Com{bt@adjust@label}).
%    \begin{macrocode}
\newcommand*\bt@set@cnt[1]{%
%<debug>    \bt@debug{setting totalcnt to #1}%
    \gdef\bt@totalctr{#1}%
}
%    \end{macrocode}
%    \end{macro}


%
% ^^A ------------------------------------------------------------
%    \subsubsection{Keyval stuff (experimental)}
% ^^A ------------------------------------------------------------
% 
%    The name `keyval lists' could be misleading, since the
%    list may contain a `key' several times (with different values).
%    The `key' is just the citation key of the reference, and the
%    value is the section label where its reference has been printed.
%    Example:
%    \begin{verbatim}
%    \@elt {ColBenh:93}{Sec:4}\@elt {RouxSmart:95}{Sec:2}
%    \@elt {Munt:93}{Sec:1}\@elt {ColBenh:93}{Sec:1}
%    \end{verbatim}
%    
%    \begin{macro}{\bt@old@keyval@list}
%    \begin{macrocode}
\newcommand*\bt@keyval@list{}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@kv@add}
%    Add the key-value pair |#1|-|#2| to the list \Com{bt@old@keyval@list};
%    |#1| is the author key, |#2| the section label. We add this to
%    the list in the form \Com{@elt}|{#1}||{#2}|.
%    \begin{macrocode}
\newcommand*\bt@kv@add[2]{%
    \protected@edef\bt@tempa{\bt@keyval@list}%
    \protected@xdef\bt@keyval@list{\noexpand\@elt{#1}{#2}\bt@tempa}%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\btCiteSect}
%    Here's an example for a user-defined command as a
%    front end the \Com{btGetVal} command: Get the label for
%    citation key |#1|, and use it along with
%    a \Com{cite} command:
%    \begin{macrocode}
\DeclareRobustCommand*\btCiteSect[1]{%
    \btGetVal{#1}%
    \cite{#1} (section\nobreakspace{}\ref{\btretval})%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\btRef}
%    Another possiblility for a user command:
%    Prints the label |#1| as a reference of type |#2|;
%    e.\,g.: \Com{btRef}|{Smith:69}||{\pageref}|.
%    \begin{macrocode}
\DeclareRobustCommand*\btRef[2]{%
    % get section label of #1 from \bt@keyval@list
    % reference type is #2
    \ifx\bt@keyval@list\@undefined
        {\bfseries{???}}%
    \else
        \bt@get@keyval{#1}{\bt@keyval@list}%
        #2{\btretval}%
    \fi
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\btGetVal}
%    Sets \Com{btretval}, for later use
%    use like, e.g.:
%    \begin{verbatim}
%    \cite{foo}\btGetVal{foo}
%    (\ref{\btretval}, {\itshape\titleref{\btretval}}).
%    \end{verbatim}
%    \begin{macrocode}
\DeclareRobustCommand*\btGetVal[1]{%
    \bt@get@keyval{#1}{\bt@keyval@list}%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\bt@print@keyvals}
%    |#1| is a list of `keys', |#2| is the value (bib section of the bibitem
%    corresponding to `key').  We write the key-value pairs wrapped into a
%    command (\Com{bt@keyval@add}) to the .aux file; this command will build up
%    a new list in the next run.  Note that values could be written twice if
%    the user has used `positive' and `all' citation lists for the same
%    bibliography. Currently, the command \Com{bt@get@keyval} will 
%    return only the value of the first key found.
%    \begin{macrocode}
\newcommand*\bt@print@keyvals[2]{%
%<debug>            \bt@debug{^^J***list is: #1}%
    \let\bt@elt\@elt%
    \def\@elt##1{%
%<debug>                \bt@debug{writing keyval: ##1,#2}%
        \protected@write\@auxout{}{%
            \string\bt@kv@add{##1}{#2}%
        }%
    }#1%
    \let\@elt\bt@elt
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\bt@get@keyval}
%    Search for keys in the list and return the value of the found key
%    as \Com{btretval}. This always returns the \emph{last} value found,
%    so if a key is stored multiple times in the list,
%    the values of the later occurrence will overwrite the values of
%    earlier occurrences (consider this when looking at the order of insertion
%    in \Com{bt@addto@keyval@list}).
%    \begin{macrocode}
\newcommand*\bt@get@keyval[2]{%
    \gdef\btretval{???}%
%    \end{macrocode}
%    First save key to list of `requested' lists;
%    only those will be printed as labels later on.
%    \begin{macrocode}
    \bt@add@elem{#1}{\bt@kv@req@list}%
    %% get value of key #1 from list #2
    \protected@edef\bt@tempa{#1}%
    \bt@elemfalse
    \let\bt@elt\@elt%
    \def\@elt##1##2{\def\bt@tempb{##1}%
        \ifx\bt@tempa\bt@tempb  %##2
            \gdef\btretval{##2}%
        \fi
    }%
    #2%
    \let\@elt\bt@elt
    \ifthenelse{\equal{\btretval}{???}}{%
        \PackageWarning{bibtopic}{%
            Key `#1' not found\MessageBreak in list of cited works%
        }%
    }{}%
}
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\bt@get@label}
%    Get value of key |#1| from list |#2|
%    \begin{macrocode}
\newcommand*\bt@get@label[2]{%
    \protected@edef\bt@tempa{#1}%
    \let\bt@elt\@elt%
    \def\@elt##1##2{\def\bt@tempb{##1}%
        \ifx\bt@tempa\bt@tempb%
        ##2
        \fi
    }%
    #2%
    \let\@elt\bt@elt
}
%    \end{macrocode}
%    \end{macro}

% ^^A --------------------------------------------------
%    \subsection{User interface}
% ^^A --------------------------------------------------
%
%    \begin{environment}{btSect}
%    Optional arg |#1| is the bibstyle,
%    |#2| is the list of \BibTeX\ files.
%    Warn if the optional argument is empty and
%    no default \Com{bibliographystyle} has been selected.
%    \begin{macrocode}
\newenvironment{btSect}[2][\bt@globalstyle]{%
    \ifthenelse{\equal{#1}{}}{%
        \PackageWarning{%
            bibtopic%
        }{%
            No \string\bibliographystyle\space given
            - \MessageBreak assuming `\bt@defaultstyle'%
        }%
        \def\bt@globalstyle{\bt@defaultstyle}%
    }{}%
%    \end{macrocode}
%    Define \Com{bt@sect}\Com{romannumeral}\Com{bt@unit@cnt} to
%    save the current \Com{bt@cited@list} (similar to what is done
%    by \Com{bt@save@list} (via the \File{.aux} file) for different
%    \Env{btUnit}s; this is the trivial case where \Com{bt@unit@cnt}
%    will always equal one, but since we don't call \Com{bt@save@list}
%    when not having \Env{btUnit}s, we have to define \Com{btsecti}
%    manually here. We define it only in case it's not defined yet):
%    \begin{macrocode}
    \expandafter\ifx\csname bt@sect\bt@unit@cnt%
            \endcsname\relax
        \expandafter\protected@xdef\csname bt@sect%
            \bt@unit@cnt\endcsname{\bt@cited@list}%
%<*debug>
        \bt@debug{list\bt@unit@cnt{} newly defined as:
            \csname bt@sect\bt@unit@cnt\endcsname}%
    \else
        \bt@debug{list\bt@unit@cnt{} was already defined as:
            \csname bt@sect\bt@unit@cnt\endcsname}%
%</debug>
    \fi
    \stepcounter{btauxfile}%
    \bt@info{bibliographystyle is `#1'\MessageBreak
            for file `\thebtauxfile .bbl'%
    }%
%    \end{macrocode}
% ^^A
%    Set flag for error checking:
%    \begin{macrocode}
    \bt@inside@secttrue
    \gdef\bt@curr@bib@file{#2}%
    \gdef\bt@sect@ref@list{}%    +code:bt@sect@ref@listReset;
    \bt@change@thb%
    \if@filesw
        \@bt@write@auxfile{#1}{*}{#2}%
    \fi
}{%
    \relax
}%
%    \end{macrocode}
%    \end{environment}
%
%    \begin{environment}{btUnit}
%    Implements the `logically independent' citation sections.
%    Most of the work is done by redefining the \Com{@citex} and
%    \Com{bibcite} commands (inside \Com{bt@setcites}).
%    \begin{macrocode}
\newenvironment{btUnit}{%
    \ifthenelse{\boolean{bt@inside@unit}}{%
        \PackageError{%
            bibtopic%
        }{%
            The `btUnit' environment cannot be nested%
        }{%
            You cannot use a `btUnit' environment inside another^^J%
            `btUnit' environment.
        }%
    }{}%
    \global\bt@inside@unittrue
%    \end{macrocode}
%    Then we write a command to the \File{.aux} file that will change
%    the \Com{bibitem} command, and we
%    activate the redefinitions of the \Com{@citex} and \Com{nocite}
%    commands in case \Package{natbib} hasn't been loaded
%    (since it has its own definitions that work with this package as well):
%    \begin{macrocode}
    \immediate\write\@auxout{%
        \string\csname\space change@bibcite\string\endcsname%
    }%
    \ifthenelse{\not\boolean{bt@natbib}}{%
        \bt@setcites
    }{}%
%    \end{macrocode}
%    Unless the \Env{unitcntnoreset} option had been used,
%    reset the bibitems counter:
%    \changes{v1.0k}{2002/06/11}{%
%        Also reset previously forgotten \chCom{bt@save@cnt}
%    }
%    \begin{macrocode}
    \ifthenelse{\not\boolean{bt@part@cont@ctr}}{%
        \def\bt@save@cnt{0}%
        \ifthenelse{\boolean{bt@natbib}}{%
            \setcounter{NAT@ctr}{0}%
        }{%
            \setcounter{enumiv}{0}% for standard styles
        }%
    }{}%
%    \end{macrocode}
%    The entire redefinition stuff with \Com{bibcite} won't work without this extra
%    level of indirection (this is again taken from \Package{chapterbib.sty}):
%    \begin{macrocode}
    \protected@xdef\the@ipfilectr{\bt@unit@cnt}%
%    \end{macrocode}
%    Then we put the command to empty \Com{bt@cited@list} into the \File{.aux} file,
%    and the command to set \Com{@extra@b@citeb}. (This is also the reason why you
%    cannot nest several \Env{btUnit} environments.)
%    \begin{macrocode}
    \immediate\write\@auxout{\string\def\string\bt@cited@list{}^^J%
                    \string\gdef\string\@extra@binfo{\@extra@b@citeb}}%
}{%
%    \end{macrocode}
%    \Com{bt@save@list} will save \Com{bt@citedlist} to a list specific to
%    the current \Env{btUnit} (using the value of \Env{bt@unit@cnt} to make it unique)
%    at the time the \File{.aux} file is read:
%    \begin{macrocode}
    \immediate\write\@auxout{\string\bt@save@list{\bt@unit@cnt}}
    \bt@stepcnt\bt@unit@cnt
    \gdef\the@ipfilectr{}%
    \immediate\write\@auxout{%
        \string\gdef\string\@extra@binfo{\@extra@b@citeb}}%
    \global\bt@inside@unitfalse
}
%    \end{macrocode}
%    \end{environment}
%
%    All the following commands do similar stuff: Apart from setting the labels
%    for the keyval thing, they all call \Com{bt@change@bibitem} to activate
%    our `fake' environments, and then input the \Env{thebibliography}
%    environment.  The only major difference between them is in setting the
%    \Com{@bt@print@\{positive$\mid$all\}@} flags that control printing inside
%    \Com{bt@call@item}.
% ^^A
%    \changes{v1.0b}{1999/09/20}{%
%       Added the \chCom{bt@curr@...} commands to the \chCom{btPrint...} commands
%    }
% ^^A
%    \begin{macro}{\btPrintCited}
%    \begin{macrocode}
\newcommand*\btPrintCited{%
    \ifthenelse{\boolean{bt@inside@sect}}{%
        \protected@edef\bt@curr@line{\the\inputlineno}%
        \def\bt@curr@cmd{\string\btPrintCited}%
        \bt@stepcnt\bt@internal@sect@cnt%
        \bt@print@citedtrue\bt@print@allfalse
        \label{Sec:\bt@internal@sect@cnt}%
        \bt@change@bibitem
        \bt@input@or@warn{\thebtauxfile}%
%    \end{macrocode}
%    For each item in \Com{bt@sect@ref@list}, write a \Com{bt@kv@add}
%    into the \File{.aux} file:
%    \begin{macrocode}
        \bt@print@keyvals{\bt@sect@ref@list}{%
            Sec:\bt@internal@sect@cnt
        }%
    }{%
        \bt@sect@err{btSect}{\btPrintCited}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\btPrintNotCited}
%    \begin{macrocode}
\newcommand*\btPrintNotCited{%
    \ifthenelse{\boolean{bt@inside@sect}}{%
        \protected@edef\bt@curr@line{\the\inputlineno}%
        \def\bt@curr@cmd{\string\btPrintNotCited}%
        \bt@stepcnt\bt@internal@sect@cnt
        \bt@print@citedfalse\bt@print@allfalse
        \label{Sec:\bt@internal@sect@cnt}%
        \bt@change@bibitem
        \bt@input@or@warn{\thebtauxfile}%
    }{%
        \bt@sect@err{btSect}{\btPrintNotCited}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\btPrintAll}
%    \begin{macrocode}
\newcommand*\btPrintAll{%
    \ifthenelse{\boolean{bt@inside@sect}}{%
        \protected@edef\bt@curr@line{\the\inputlineno}%
        \def\bt@curr@cmd{\string\btPrintAll}%
        \bt@stepcnt\bt@internal@sect@cnt
        \bt@print@citedfalse\bt@print@alltrue
        \label{Sec:\bt@internal@sect@cnt}%
        \bt@change@bibitem
        \bt@input@or@warn{\thebtauxfile}%
        \bt@print@keyvals{\bt@sect@ref@list}%
            {Sec:\bt@internal@sect@cnt}%
    }{%
        \bt@sect@err{btSect}{\btPrintAll}%
    }%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{environment}{bibtopics}
%    The bibtopics environment of bibtopics.sty, version November '97
%    \begin{macrocode}
\newenvironment{bibtopics}[2]{%
    \begin{btSect}[#1]{#2}%
    \btPrintAll
}{%
    \end{btSect}%
}
%    \end{macrocode}
%    \end{environment}
%
%    \begin{environment}{bibunit}
%    The obsolete bibunit command.
%
%    Its syntax:
%    \begin{verbatim}
%    \begin{bibunit}[plain]  
%    \nocite{*}              
%    \putbib[ArtDansRev]     
%    \end{bibunit}           
%    \end{verbatim}
%    This implementation needn't share all the features of
%    \Env{btSect} (like preparing the lists of cited authors)
%    because it's only for compatibility with existing documents.
%    \begin{macrocode}
\newcommand\bt@bibstyle{}
\newcommand\bt@citation{}
\newcommand\bt@bibdata{}
\newenvironment{bibunit}[1][\bt@globalstyle]{%
    \ifx#1\@empty
        \PackageWarning{%
            bibtopic%
        }{%
            No \string\bibliographystyle\space given
            - \MessageBreak assuming `\bt@defaultstyle'%
        }%
        \def\bt@globalstyle{\bt@defaultstyle}%
    \fi
    \def\bt@bibstyle{#1}%
    \def\nocite##1{\def\bt@citation{##1}}%
    \def\cite##1{\def\bt@citation{##1}}%
    \gdef\putbib[##1]{\gdef\bt@bibdata{##1}}%
    \stepcounter{btauxfile}%
}{%
    \bt@change@thb
    \if@filesw
        \@bt@write@auxfile{\bt@bibstyle}{\bt@citation}{\bt@bibdata}%
    \fi
%    \end{macrocode}
%    Then we call \Com{btPrintAll}:
%    \begin{macrocode}
        \bt@inside@secttrue
        \btPrintAll
}
%    \end{macrocode}
%    \end{environment}
%
%
% ^^A --------------------------------------------------
%    \subsection{Warnings and error messages}\label{sec:PackageWarnings}
% ^^A --------------------------------------------------
%
%    \begin{macro}{\bt@bibitemcheck}
%    Warn if no bibitem matching the current specification
%    (cited\slash not cited) have been found in this
%    \Env{thebibliography} environment.
% ^^A
%    \changes{v1.0b}{1999/09/20}{%
%       Improved the error message by adding the \chCom{bt@curr@...} commands
%    }
% ^^A
%    \begin{macrocode}
\newcommand*\bt@bibitemcheck{%
    \ifthenelse{\not\boolean{bt@found@item}}{%
        \PackageWarningNoLine{%
            bibtopic%
        }{%
            No appropriate bibitems found for command\MessageBreak %
            \bt@curr@cmd\space on line \bt@curr@line%     +code:bt@curr@cmd;
        }%
    }{}%
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\bt@sect@err}
%    Give an error message saying that a command |#2| is being used
%    outside of the environment |#1| it belongs to:
%    \begin{macrocode}
\newcommand*\bt@sect@err[2]{%
    \PackageError{%
        bibtopic%
    }{%
        You can't use `\string#2' outside of `#1'%
    }{%
        See the documentation on the `\string#2' command\MessageBreak
        in `bibtopic.dvi' for details.
    }%
}
%    \end{macrocode}
%    \end{macro}


%    \begin{macro}{\bt@bibtex@warning}
%    Instead of \LaTeX's silent \ErrMessage{No file xxx.bbl}, we issue
%    a more obtrusive warning. Called by \Com{bt@files@warnings}.
%    \begin{macrocode}
\newcommand*\bt@bibtex@warning[1]{%
    \PackageWarningNoLine{%
        bibtopic%
    }{%
        Please (re)run BibTeX on the file(s):%
        \expandafter\MessageBreak#1%
        and after that rerun LaTeX%
    }%
}
%    \end{macrocode}
%    \end{macro}


%    \begin{macro}{\bt@files@warnings}
%    Print warning about undefined \Com{harvarditem} commands, and about
%    files being outdated.
%    \begin{macrocode}
\newcommand*\bt@files@warnings{%
    \ifthenelse{\boolean{bt@harvard@errs}}{%
        \PackageError{%
            bibtopic%
        }{%
            Your command \string\harvarditem\space was ignored%
        }{%
            `bibtopic' currently supports the `\string\harvarditem'
            command^^J
            only in connection with the `natbib' package. So either^^J%
            load this package, or change the `\string\citationstyle' command
            to some^^J%
            non-harvard style.^^J%
            If you hit RETURN now, some of your bibliographies will be empty.
        }%
    }{}%
    \ifthenelse{\boolean{bt@overridden@numargs}}{%
        \ifthenelse{\boolean{bt@warn@override}}{%
            \PackageWarningNoLine{%
                bibtopic%
            }{%
                The numerical argument in some `\string\bibitem' commands^^J%
                has been ignored. Using one of the package options^^J%
                `overridenumbers' or `dontoverridenumbers' will make^^J%
                this warning go away.^^J%
                Please see the documentation on these options^^J%
                in `bibtopic.dvi' for more details.
            }%
        }{}%
    }{}%
    \ifthenelse{\equal{\bt@warn@files}{}}{%
        \relax
    }{%
        \bt@mk@warning@list{\bt@warn@files}%
        \bt@bibtex@warning{\the\@temptokena}%
%    \end{macrocode}
%    \changes{v1.0k}{2002/06/11}{%
%        Disable the `rerun latex' message when .bbl files are missing to avoid confusion
%    }
%    Also disable the `rerun latex' message in this case, since multiple messages would
%    confuse the user:
%    \begin{macrocode}
        \def\bt@helpctr{\bt@totalctr}%
    }%
}
%    \end{macrocode}
%    \end{macro}


%    \begin{macro}{\bt@input@or@warn}
%    Input a \File{.bbl} file if it exists; else,
%    add it to our list of missing\slash outdated files.
%    \begin{macrocode}
\newcommand*\bt@input@or@warn[1]{%
    \IfFileExists{#1.bbl}%
    {%
        \input#1.bbl%
    }{%
        \bt@if@elem{#1}{\bt@warn@files}{%
            \relax
        }{%
            \PackageWarningNoLine{%
                bibtopic%
            }{%
                No file #1.bbl%
            }%
%    \end{macrocode}
%    Skip the extra warning using \Com{bt@warn@files} if \Env{normalwarnings} is active:
%    \begin{macrocode}
            \ifbt@normalwarnings
            \else
                \bt@append@list{#1}{\bt@warn@files}%
            \fi
        }%
    }%
}%
%    \end{macrocode}
%    \end{macro}


%    \begin{macro}{\bt@warn@outdated}
%    Append |#1| to \Com{bt@warn@files} just in case it's not
%    yet in this list:
%    \begin{macrocode}
\newcommand*\bt@warn@outdated[1]{%
    \bt@if@elem{#1}{\bt@warn@files}{%
        \relax
    }{%
        \bt@infoNoLine{Marking #1.bbl as outdated}%
        \bt@append@list{#1}{\bt@warn@files}%
    }%
    \ifthenelse{\not\boolean{bt@natbib}}{%
%    \end{macrocode}
%    Don't continue reading, since this would only lead to errors anyway
%    (heuristic):
%    \begin{macrocode}
        \global\let\bt@item\relax
        \global\let\endbt@item\relax
    }{}%
}%
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%   \iffalse meta-comment
% ^^A --- BibTeX file articles.bib ---
%
%<*articles.bib>
The following entry is an example for what's allowed by
BibTeX syntax (see btxdoc.dvi).

@incollection
(
    RouxSmart:95
    ,
    author    = "M. Roux and J. Smart",
    title     = "A Model of Medical Knowledge Representation, Application
                 to the Reports Analysis of Descriptive Pathology",
    booktitle = "Methods of Information in Medecine",
    note      = {\`A para\^{\i}tre},
    publisher = "Schattauer",
    address   = "Holland",
    year      = 1995
)

@article{Schwind:96,
    author    = {Camilla B. Schwind},
    title     = {Knowledge Based Language Tutoring},
    journal   = {Computer Assisted Language Learning}, 
    publisher = {Svets},
    year      = 1996,
    note      = {\`A para\^{\i}tre}
}

%</articles.bib>
%
% ^^A --- BibTeX file books.bib ---
%
%<*books.bib>
@book{ColBenh:93,
   editor = "Fr\'ed\'eric Benhamou and Alain Colmerauer" ,
   title = "Constraint Logic programming, Selected Research",
   publisher = "MIT Press",
   year = 1993
}

@book{Munt:93,
   author =    {Tra{\"\i}an Muntean},
   title =     {Puces tr\`es performantes},
   publisher = {Hatier},
   address =   {Paris},
   series = {Terres du futur, Les Editions UNESCO},
   year =      1993,
}

%</books.bib>
%
% ^^A --- .bbl files produced from .bib files above ---
%
%<*bibtopic2.bbl>
\begin{thebibliography}{1}

\bibitem{RouxSmart:95}
M.~Roux and J.~Smart.
\newblock A model of medical knowledge representation, application to the
  reports analysis of descriptive pathology.
\newblock In {\em Methods of Information in Medecine}. Schattauer, Holland,
  1995.
\newblock \`A para\^{\i}tre.

\bibitem{Schwind:96}
Camilla~B. Schwind.
\newblock Knowledge based language tutoring.
\newblock {\em Computer Assisted Language Learning}, 1996.
\newblock \`A para\^{\i}tre.

\end{thebibliography}
%</bibtopic2.bbl>
%<*bibtopic1.bbl>
\begin{thebibliography}{Mun93}

\bibitem[BC93]{ColBenh:93}
Fr\'ed\'eric Benhamou and Alain Colmerauer, editors.
\newblock {\em Constraint Logic programming, Selected Research}.
\newblock MIT Press, 1993.

\bibitem[Mun93]{Munt:93}
Tra{\"\i}an Muntean.
\newblock {\em Puces tr\`es performantes}.
\newblock Terres du futur, Les Editions UNESCO. Hatier, Paris, 1993.

\end{thebibliography}
%</bibtopic1.bbl>
%
% ^^A --- sample .tex file including the bibliographies ---
% 
%<*sample.tex>
\documentclass[10pt]{article}
\usepackage{bibtopic}
\begin{document}
\bibliographystyle{alpha}

\section{Testing}
Let's cite all the books: \cite{ColBenh:93} and
\cite{Munt:93}; and an article: \cite{RouxSmart:95}.

\begin{btSect}{books}
\section{References from books}
\btPrintCited
\end{btSect}

\begin{btSect}[plain]{articles}
\section{References from articles}
\btPrintCited

\section{Articles not cited}
\btPrintNotCited
\end{btSect}
\end{document}
%</sample.tex>
%
%   \fi
%  ^^A \typeout{^^Juncomment FINALE before releasing!!!^^J}
%  \Finale
\endinput

