Debian Codegraph @

texmf-dist/source/latex/bibtopic/bibtopic.dtx

raw
1 % \iffalse meta-comment
2 % bibtopic.dtx
3 % Docstrip archive, run through LaTeX.
4 % See bibtopic.ins for details on how to produce the style file/documentation.
5 %
6 % Copyright (C) 1998-2000 P. Basso, S. Ulrich
7 % Copyright (C) 2001-2003 S. Ulrich
8 %
9 % Please send bug reports to: <[email protected]>
10 %
11 % This program is free software; you can redistribute it and/or
12 % modify it under the terms of the GNU General Public License
13 % as published by the Free Software Foundation; either version 2
14 % of the License, or (at your option) any later version.
15 %
16 % This program is distributed in the hope that it will be useful,
17 % but WITHOUT ANY WARRANTY; without even the implied warranty of
18 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 % GNU General Public License for more details.
20 %
21 % You should have received a copy of the GNU General Public License
22 % along with this program; if not, write to the Free Software
23 % Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 %
25 %
26 %
27 %<*driver>
28 \ProvidesFile{bibtopic.drv}[1999/06/01 v1.0 Driver for bibtopic package]
29 \documentclass[10pt,a4paper]{ltxdoc}
30 \usepackage[normalwarnings]{bibtopic}
31 \errorcontextlines\maxdimen
32 %\usepackage{fullpage}
33 \RequirePackage{url}%
34 \RequirePackage{ifthen}%
35 % \IfFileExists{hyperref.sty}{%
36 % \RequirePackage{hyperref}%
37 % }{}
38 \GetFileInfo{bibtopic.sty}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42 \setcounter{IndexColumns}{2} % make a twocolumn index
43 \setlength{\columnseprule}{0pt} % no rules between columns ...
44 \setlength{\columnsep}{2em} % ... but more spacing instead.
45 \setcounter{unbalance}{4}
46 \setlength{\IndexMin}{100pt}
47 \OnlyDescription % uncomment this line to suppress printing the source code
48
49 \makeatletter
50 % Change the font for verbatim listings to \footnotesize.
51 % The following hook is a workaround for a bug in doc.sty v1.9z:
52 % setting \MacroFont gets overwritten by the \let assignment.
53 \AtBeginDocument{%
54 \renewcommand\MacroFont{\fontencoding\encodingdefault
55 \fontfamily\ttdefault
56 \fontseries\mddefault
57 \fontshape\updefault
58 \footnotesize}%
59 % work around a bug in doc.sty (reported & fixed) where the
60 % second \special@index is just \index, causing the
61 % pagenumber instead of the code line number being written
62 % into the second-level entry after `environments:'
63 \def\SpecialMainEnvIndex#1{\@bsphack
64 \special@index{#1\actualchar
65 {\string\ttfamily\space#1}
66 (environment)%
67 \encapchar main}%
68 % changed \index to \special@index and \protect to \string:
69 \special@index{environments:\levelchar{\string\ttfamily\space#1}\encapchar
70 main}\@esphack}
71 \renewcommand\AltMacroFont{\fontencoding\encodingdefault
72 \fontfamily\ttdefault
73 \fontseries\mddefault
74 % \fontshape\sldefault
75 \fontshape\itdefault
76 \footnotesize}%
77 \let\macro@font=\MacroFont
78 }%
79 % don't show underfull hboxes in index/glossary:
80 \g@addto@macro{\IndexParms}{\hbadness=10000}
81 \g@addto@macro{\GlossaryParms}{\hbadness=10000}
82 \makeatother
83
84 \begin{document}
85 \DocInput{bibtopic.dtx}
86 % \PrintIndex
87 % \PrintChanges
88 \end{document}
89 %</driver>
90 %
91 % ^^A See CTAN:tools/filehdr/filehdr.dvi for an explanation for the following stuff
92 %
93 % ===================================================================
94 % @LaTeX-package-file{
95 % version = "1.1a",
96 % date = "2002/08/22",
97 % filename = "bibtopic.sty",
98 % author-1 = "Pierre Basso",
99 % email-1 = "[email protected]",
100 % author-2 = "Stefan Ulrich",
101 % email-2 = "[email protected]",
102 % codetable = "ISO/ASCII",
103 % keywords = "sectioned bibliographies, multiple bibliographies,
104 % bibliographies by topic, bibliographies by topics,
105 % BibTeX",
106 % supported = "yes",
107 % docstring = "User manual and documented source code and for the
108 % LaTeX package bibtopic.sty"
109 % }
110 % ===================================================================
111 % \fi
112 %
113 %
114 % \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
115 % \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
116 % \DoNotIndex{\if,\ifnum,\ifdim,\ifcat,\ifmmode,\ifvmode,\ifhmode,%
117 % \iftrue,\iffalse,\ifvoid,\ifx,\ifeof,\ifcase,\else,\or,\fi,\loop,\do}
118 % \DoNotIndex{\box,\copy,\setbox,\unvbox,\unhbox,\hbox,%
119 % \vbox,\vtop,\vcenter}
120 % \DoNotIndex{\@empty,\immediate,\write}
121 % \DoNotIndex{\egroup,\bgroup,\expandafter,\begingroup,\endgroup}
122 % \DoNotIndex{\divide,\advance,\multiply,\count,\dimen}
123 % \DoNotIndex{\relax,\space,\string}
124 % \DoNotIndex{\csname,\endcsname,\@spaces,\openin,\openout,%
125 % \closein,\closeout}
126 % \DoNotIndex{\catcode,\endinput}
127 % \DoNotIndex{\jobname,\message,\read,\the,\noexpand}
128 % \DoNotIndex{\hsize,\vsize,\hskip,\vskip,\kern,\hfil,\hfill,\hss}
129 % \DoNotIndex{\m@ne,\z@,\@m,\z@skip,\@ne,\tw@,\p@}
130 % \DoNotIndex{\DeclareRobustCommand,\DeclareOption,\newcommand,\newcommand*}
131 % \DoNotIndex{\newcount,\newif,\newlinechar,\newread,\newtoks,\newwrite}
132 % \DoNotIndex{\dp,\wd,\ht,\vss,\unskip,\ifthenelse}
133 %
134 % ^^A --------------------------------------------------
135 %
136 % \CheckSum{1747}
137 %
138 % \CharacterTable
139 % {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
140 % 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
141 % Digits \0\1\2\3\4\5\6\7\8\9
142 % Exclamation \! Double quote \" Hash (number) \#
143 % Dollar \$ Percent \% Ampersand \&
144 % Acute accent \' Left paren \( Right paren \)
145 % Asterisk \* Plus \+ Comma \,
146 % Minus \- Point \. Solidus \/
147 % Colon \: Semicolon \; Less than \<
148 % Equals \= Greater than \> Question mark \?
149 % Commercial at \@ Left bracket \[ Backslash \\
150 % Right bracket \] Circumflex \^ Underscore \_
151 % Grave accent \` Left brace \{ Vertical bar \|
152 % Right brace \} Tilde \~}
153 %
154 %
155 % ^^A --------------------------------------------------
156 % ^^A quite a few (I'm afraid) definitions for formatting this
157 % ^^A documentation ...
158 % ^^A --------------------------------------------------
159 %
160 % \makeatletter
161 % \newcommand\writeauxfile[1]{\immediate\write\@auxout{#1}}^^A for the `implementation' boolean
162 % \hfuzz.5pt ^^A tolerate overfull \hboxes up to this measure
163 % \renewcommand\floatpagefraction{.8}
164 % \hyphenation{bib-lio-gra-phy bib-lio-gra-phies}
165 % \let\MakeUppercase\itshape ^^A I don't like those uppercase headlines ...
166 % \let\slshape\itshape ^^A ... nor slanted fonts.
167 % \pagestyle{headings}
168 % \frenchspacing
169 % \overfullrule=5pt
170 %
171 %
172 % ^^A This command prints the reference set by label #2.
173 % ^^A #1 and #3 are stuff to be put before and after the formatted reference,
174 % ^^A so the referencing can be made optional (e.g. for the user interface
175 % ^^A description) if the code section isn't included. To detect this, we
176 % ^^A define the flag (= command) \implementation in the .aux file immediately after
177 % ^^A \StopEventually as `T' and check inside \CodeRef if \implementation
178 % ^^A is still undefined (working with booleans became too tricky because they
179 % ^^A would have to be defined before the .aux file is read; defining them inside the
180 % ^^A .aux file (using a \write) somehow didn't work).
181 % ^^A The reference is printed as a number in square brackets, in a slightly
182 % ^^A (1pt) smaller font.
183 %
184 % \newcounter{bt@curr@font@size}
185 % \newcommand\CodeRef[3]{^^A
186 % ^^A compute smaller fontsize:
187 % \setcounter{bt@curr@font@size}{\f@size}^^A
188 % \addtocounter{bt@curr@font@size}\m@ne\relax^^A
189 % \ifx\implementation\undefined
190 % \message{.}^^A info
191 % \else
192 % \message{:}^^A info
193 % #1{\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [\printrefs#2,\end]}#3^^A
194 % ^^A #1{\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [\ref{#2}]}#3^^A
195 % \fi
196 % }
197 % \newcommand\printrefs{}
198 % \def\printrefs#1,#2\end{^^A
199 % \ifthenelse{\equal{#2}{}}{^^A
200 % \ref{#1}^^A
201 % }{^^A
202 % \ref{#1}, ^^A
203 % \printrefs#2\end
204 % }^^A
205 % }
206 % ^^A \ifhave@hyperref
207 % ^^A \def\lineref#1{\@safe@activestrue\expandafter\@setref\csname r@#1\endcsname\@firstoffive{#1}\@safe@activesfalse}
208 % ^^A \else
209 % ^^A \def\lineref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
210 % ^^A \fi
211 %
212 % ^^A Fake a \CodeRef command for demonstrative purposes:
213 % \newcommand\ShowCodeRef[1]{^^A
214 % \setcounter{bt@curr@font@size}{\f@size}^^A
215 % \addtocounter{bt@curr@font@size}\m@ne\relax^^A
216 % {\fontsize{\thebt@curr@font@size}{\thebt@curr@font@size}\selectfont [#1]}^^A
217 % }
218 % \renewcommand\listfigurename{Figures}
219 %
220 % ^^A BibTeX logo (also works for bold, where a simple \scshape would fail)
221 % \DeclareRobustCommand{\BibTeX}{^^A
222 % B\kern-.05em^^A
223 % ^^A% The following has been taken from the definition of the
224 % ^^A% \LaTeX macro, see `ltlogos.dtx'
225 % \hbox{$\m@th$^^A % %% force math size calculations
226 % \csname S@\f@size\endcsname
227 % \fontsize\sf@size\z@
228 % \math@fontsfalse\selectfont
229 % I\kern-.025emB}^^A
230 % \kern-.08em^^A
231 % \-\TeX^^A
232 % }
233 %
234 % ^^A This allows long command names to be hyphenated:
235 % \begingroup\makeatother\gdef\btAtSign{@}\endgroup
236 % \def\btAt{\penalty\@M\-\btAtSign\penalty\@M \hskip\z@skip}
237 % \def\allowhyphens{\penalty\@M \hskip\z@skip}
238 % \newcommand\BTbegEnv[1]{^^A
239 % {^^A
240 % \ttfamily\bslash begin^^A
241 % \penalty\@M\hskip\z@skip
242 % \Obr\Env{\allowhyphens #1}\Cbr
243 % ^^A \penalty\@M \hskip\z@skip
244 % }^^A
245 % }
246 % \newcommand\BTendEnv[1]{^^A
247 % {^^A
248 % \ttfamily{\bslash end\penalty\@M
249 % \hskip\z@skip\Obr\Env{\allowhyphens #1}\Cbr
250 % \penalty\@M \hskip\z@skip}^^A
251 % }^^A
252 % }
253 %
254 % \newcommand\Com{^^A
255 % \begingroup\catcode`\@\active\btCom
256 % }
257 % \newcommand\chCom[1]{^^A
258 % \texttt{\string\char`\\#1}^^A
259 % }
260 % \newcommand\chEnv{\texttt}
261 % \newcommand\Env{^^A
262 % \begingroup\catcode`\@\active\btEnv
263 % }
264 %
265 % \begingroup
266 % \catcode`\@\active
267 % \gdef\btCom#1{^^A
268 % \def@{\btAt}^^A
269 % \ttfamily\hyphenchar\font=`\-\bslash #1\endgroup
270 % }
271 % \gdef\btEnv#1{^^A
272 % \def@{\btAt}^^A
273 % \ttfamily\hyphenchar\font=`\-#1\endgroup}
274 % \endgroup
275 %
276 % \newcommand\Obr{{\ttfamily\char`\{}}
277 % \newcommand\Cbr{{\ttfamily\char`\}}}
278 %
279 % ^^A Some handy abbreviations (aka `logical markup commands' ...)
280 % \newcommand\Package[1]{\textsf{#1}}
281 % \newcommand\ThisPackage{\Package{\filename}}
282 % \newcommand\File[1]{\texttt{#1}}
283 % \newcommand\ImportantNote[1]{\textbf{Note: }#1}
284 %
285 % ^^A to highlight changes that might be important for users:
286 % \newcommand\UserChange[1]{\mbox{}\marginpar{\raggedleft{#1}}}^^A
287 %
288 % ^^A description-like environment for describing commands etc.
289 % \newenvironment{UserCommands}{^^A
290 % \begin{list}{}{^^A
291 % \renewcommand\makelabel[1]{^^A
292 % \parbox[b]{\labelwidth}{^^A
293 % \makebox[0pt][l]{##1}\\ \mbox{}^^A
294 % }\hfil\relax
295 % }^^A
296 % \setlength\labelwidth\parindent
297 % \setlength\leftmargin\labelwidth
298 % \addtolength\leftmargin\labelsep
299 % }^^A
300 % }{^^A
301 % \end{list}^^A
302 % }
303 %
304 % ^^A for formatting longish stuff in typewriter font
305 % \newcommand*\ttsloppy{\spaceskip.333em plus.11em minus.11em}
306 % \newcommand*\ErrMessage[1]{`{\ttfamily\ttsloppy\hyphenchar\font=`\-#1}'}
307 %
308 % ^^A for printing background information/less important stuff in a smaller font size:
309 % \newenvironment{BackgroundNote}{^^A
310 % \medskip\footnotesize
311 % }{^^A
312 % \par
313 % }^^A
314 % ^^A
315 % ^^A doc.sty doesn't have a command for adding package *options* to the index
316 % ^^A (only commands and environments) - define one:
317 % ^^A
318 % \newcommand*\Option[1]{^^A
319 % \topsep\MacroTopsep
320 % \trivlist
321 % \protected@edef\saved@macroname{\string#1}^^A
322 % \def\makelabel##1{\llap{##1}}^^A
323 % \macro@cnt\@ne
324 % \item[\PrintMacroName{#1}]^^A
325 % \global\advance\c@CodelineNo\@ne
326 % \bt@SpecialMainOptIndex{#1}^^A
327 % \global\advance\c@CodelineNo\m@ne
328 % \ignorespaces
329 % }
330 %
331 % \newcommand*\bt@SpecialMainOptIndex[1]{^^A
332 % \@bsphack
333 % \special@index{^^A
334 % #1\actualchar{\string\ttfamily\space#1} ^^A
335 % (option)\encapchar main^^A
336 % }^^A
337 % \special@index{^^A
338 % options:\levelchar{\string\ttfamily\space#1}\encapchar main
339 % }^^A
340 % \@esphack
341 % }
342 %
343 % ^^A
344 % ^^A To be added manually to the option descriptions in the `user' part of the
345 % ^^A doc (we also used the \SpecialUsageIndex and \SpecialEnvIndex commands
346 % ^^A directly instead of \DescribeEnv etc. to avoid having too much stuff in the margins).
347 % ^^A
348 % \newcommand*\BTSpecialOptIndex[1]{\@bsphack
349 % \index{^^A
350 % #1\actualchar{\protect\ttfamily#1} (option)^^A
351 % \encapchar usage^^A
352 % }^^A
353 % \index{^^A
354 % options:\levelchar{\protect\ttfamily#1}^^A
355 % \encapchar usage^^A
356 % }^^A
357 % \@esphack
358 % }
359 %
360 % ^^A ----------------------------------------
361 % ^^A for formatting figures
362 % ^^A ----------------------------------------
363 % ^^A
364 % ^^A A rule to separate figures from the text:
365 % ^^A
366 % \newcommand\BegRule[1][]{^^A
367 % \ifthenelse{\equal{#1}{}}{^^A
368 % \noindent{\makebox[\textwidth][t]{\hrulefill}}^^A
369 % }{^^A
370 % \noindent{\makebox[\textwidth][t]{\hrulefill\raisebox{-.5ex}{ \small\ttfamily#1 }\hrulefill}}^^A
371 % }^^A
372 % }
373 % \newcommand\EndRule{\noindent\rule[\baselineskip]{\textwidth}{.6pt}}
374 %
375 % ^^A
376 % ^^A Here we use the above rules:
377 % ^^A
378 % \newenvironment{Filelisting}[1]{^^A
379 % \medskip\BegRule[#1]\bgroup\footnotesize\verbatim
380 % }{^^A
381 % \endverbatim
382 % \egroup\EndRule
383 % }
384 %
385 % ^^A
386 % ^^A redefine captions (some users might not have caption2e installed):
387 % ^^A
388 % \newcommand\capfont{\itshape}
389 % \newcommand\capsize{\small}
390 % \def\@caption#1[#2]#3{^^A
391 % \par
392 % \addcontentsline{^^A
393 % \csname ext@#1\endcsname^^A
394 % }{#1}{\protect\numberline{\csname the#1\endcsname}{\ignorespaces #2}^^A
395 % }^^A
396 % \begingroup
397 % \@parboxrestore
398 % \normalsize
399 % \@makecaption{^^A
400 % {\capfont\capsize\csname fnum@#1\endcsname:}^^A
401 % }{^^A
402 % {\capsize\ignorespaces #3}^^A
403 % }^^A
404 % \par
405 % \endgroup
406 % }
407 % \newdimen\@tempdimb
408 % \renewcommand\@makecaption[2]{^^A
409 % \vskip\abovecaptionskip
410 % \sbox\@tempboxa{#1 }^^A
411 % \@tempdimb\wd\@tempboxa
412 % \sbox\@tempboxa{#1 #2}^^A
413 % \ifdim \wd\@tempboxa >\hsize
414 % \@tempdima.8\textwidth
415 % \centering\parbox{\@tempdima}{#1 #2}
416 % ^^A \advance\@tempdima-\@tempdimb
417 % ^^A \parbox{\@tempdima}{#2}}
418 % \else
419 % \global \@minipagefalse
420 % \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}^^A
421 % \fi
422 % \vskip\belowcaptionskip
423 % }
424 %
425 % ^^A For the example in figure \ref{fig:output}, we need something that looks like a
426 % ^^A section heading (but with a smaller fontsize, and without stepping the counters).
427 % ^^A The command `\fakesections' makes the redefinitions required for this, so
428 % ^^A that we can use the normal `\section' command to get the desired output.
429 % ^^A (All of this is copied from the standard classes, with the appropriate
430 % ^^A omissions/changes).
431 % \newcounter{helpcnt}
432 % \newcommand\fakesections{^^A
433 % \setcounter{helpcnt}{0}
434 % \def\section{\@startsection {section}{1}{\z@}^^A
435 % {-3.5ex \@plus -1ex \@minus -.2ex}^^A
436 % {2.3ex \@plus.2ex}^^A
437 % {\normalfont\normalsize\bfseries}}^^A
438 % \def\@sect##1##2##3##4##5##6[##7]##8{^^A
439 % \ifnum ##2>\c@secnumdepth
440 % \let\@svsec\@empty
441 % \else
442 % \refstepcounter{helpcnt}^^A
443 % \protected@edef\@svsec{\@seccntformat{helpcnt}\relax}^^A
444 % \fi
445 % \@tempskipa ##5\relax
446 % \ifdim \@tempskipa>\z@
447 % \begingroup
448 % ##6{^^A
449 % \@hangfrom{\hskip ##3\relax\@svsec}^^A
450 % \interlinepenalty \@M ##8\@@par
451 % }^^A
452 % \endgroup
453 % \csname ##1mark\endcsname{##7}^^A
454 % \else
455 % \def\@svsechd{^^A
456 % ##6{\hskip ##3\relax \@svsec ##8}^^A
457 % \csname ##1mark\endcsname{##7}^^A
458 % \addcontentsline{toc}{##1}{^^A
459 % \ifnum ##2>\c@secnumdepth \else
460 % \protect\numberline{\csname the##1\endcsname}^^A
461 % \fi
462 % ##7}^^A
463 % }^^A
464 % \fi
465 % \@xsect{##5}^^A
466 % }^^A
467 % }
468 % ^^A
469 % ^^A We'd like to have some sort of referencing ability
470 % ^^A to the individual lines of code in the `code' section.
471 % ^^A The problem with this is that the labelling commands should not
472 % ^^A be printed inside the code section, neither in the .dtx nor in the .sty file.
473 % ^^A So we define `+' as active character that will expand to `\linelabel'
474 % ^^A inside the documentation file and will eat its argument inside the .ins file.
475 %
476 % ^^A `+' is made active, use this instead:
477 % \DeclareRobustCommand\BTplus{+}
478 %
479 % \catcode`\+13\relax
480 % \def+#1;{^^A
481 % ^^A some info on what's going on:
482 % \message{[ln.\number\c@CodelineNo]}^^A
483 % \protected@edef\@currentlabel{\number\c@CodelineNo}^^A
484 % \label{#1}^^A
485 % }
486 % \makeatother
487 %
488 % \changes{v0.1}{1998/01/12}{%
489 % Rewrite of P. Basso's \Package{bibtopics.sty}
490 % and added english documentation
491 % }
492 % \changes{v0.1a}{1998/01/25}{%
493 % Added the `dot' and `slow' options. Removed the
494 % first non-optional argument of \texttt{btSect}; \texttt{.aux}
495 % file name should now be set by redefining the \chCom{thebtauxfile}
496 % command. Using command names instead of list lookup is default now;
497 % the `slow' option still uses the lists
498 % }
499 % \changes{v0.1b}{1998/02/24}{%
500 % Replaced `normalheadings' option by `printheadings'
501 % to avoid conflict with KOMA classes
502 % }
503 % \changes{v1.0c}{2000/01/07}{%
504 % Added natbib v7 compatibility; some minor changes
505 % }
506 % \changes{v1.0d}{2000/06/17}{%
507 % Fixed bug: \chCom{citation} commands may now
508 % contain comma-separated list of strings (as used by cite.sty)
509 % instead of one string only.
510 % Minor changes in the documentation
511 % }
512 % \changes{v1.0e}{2000/06/25}{%
513 % Made it backref (hyperref.sty) compatible
514 % }
515 % \changes{v1.0f}{2000/08/22}{^^A
516 % Added the `defaultbib' option
517 % }
518 % \changes{v1.0g}{2000/08/23}{%
519 % Removed the checks/warnings w.r.t. `KOMA' classes/no KOMA bibliography
520 % }
521 % \changes{v1.0h}{2000/09/08}{%
522 % Removed restriction that commands between \chCom{begin\{thebibliography\}}
523 % and first \chCom{bibitem} were ignored. Removed the \chEnv{btunits} option
524 % (no longer needed). Minor changes
525 % }
526 % \changes{v1.0j}{2000/10/17}{%
527 % Fixed problems with babel's redefinition of \chCom{ifthenelse}
528 % (with babel, last item inside \chCom{ifthenelse} mustn't be a
529 % command taking arguments; see also bug report babel/2625)
530 % }
531 % \changes{v1.0k}{2002/06/11}{%
532 % Fixed a bug with bibitem counter not properly reset by btUnit
533 % }
534 % \changes{v1.0k}{2002/08/22}{%
535 % Fixed an incompatibility with KOMA classes v2.9
536 % }
537 % \changes{v1.1}{2004/01/16}{%
538 % Fixed an incompatibility with jurabib's ibidem mechanism for bib entries
539 % }
540 % \changes{v1.1a}{2006/09/08}{%
541 % Documented bug with alphabetical suffixes for multiple entries with
542 % same author and year.
543 % }
544 %
545 % ^^A --------------------------------------------------
546 % \title{\ThisPackage}
547 % \author{^^A
548 % Pierre Basso\\
549 % {\texttt{[email protected]}}
550 % \and
551 % Stefan Ulrich\\
552 % {\texttt{[email protected]}}^^A
553 % }
554 % \date{\filedate\ \fileversion\\[1ex] {\footnotesize CTAN: \url{macros/latex/contrib/supported/bibtopic/}}}
555 % \maketitle
556 % ^^A --------------------------------------------------
557 % \begin{abstract}
558 % \ThisPackage\ is a revised version of P. Basso's
559 % \Package{bibtopics.sty}\footnote{The name has been truncated to
560 % fit the 8\BTplus 3 scheme of certain OSes.}. It allows for
561 % bibliographic references which are taken from several \File{.bib}
562 % files and written to separate bibliographies by \LaTeX. These
563 % bibliographies may be considered as covering different topics
564 % (hence the name) or different material (such as references from
565 % articles, references from books, \dots). The package works
566 % exclusively on the \LaTeX\ side of things; it won't help your
567 % with constructing the the different \File{.bib} files for the
568 % various topics.\footnote{There are several tools that may
569 % help you with doing this; see section~\ref{sec:tools} for details
570 % about this.}
571 %
572 % Besides from offering features the former version didn't have,
573 % this version is compatible with various document classes and
574 % bibliographic styles (such as the \textsc{KOMA} classes
575 % and the \Package{natbib} package). The package works
576 % with \LaTeX2e\ only. It is currently maintained by
577 % S.~Ulrich; please send bug reports or feature requests to
578 % \texttt{[email protected]}.
579 %
580 %
581 %
582 % \end{abstract}
583 %
584 % ^^A --------------------------------------------------
585 % \tableofcontents
586 % \listoffigures\bigskip
587 % ^^A --------------------------------------------------
588 % \iffalse
589 % Especially in the humanities there's often a need to have
590 % several bibliographies in a document covering different topics or
591 % material from different sources; e.\,g., people doing historical
592 % studies may want to put their original sources into one
593 % bibliography and the secondary writings into another; or one
594 % might want to list all articles in one bibliography and books in
595 % anoter, and so on. This package should help you incorporating
596 % these different bibliographies into your \LaTeX\ document; the
597 % database files for \BibTeX\ will still have to be constructed
598 % independently, according to your actual criteria.
599 % \fi
600 % ^^A --------------------------------------------------
601 % \section{Example of use}\label{sec:example}
602 % ^^A --------------------------------------------------
603 % Here's a short example showing the main features of
604 % \ThisPackage. Let's assume that you want to have two separate
605 % bibliographies in your document: References to \textit{books}
606 % (with \File{books.bib} as bibliography file) and
607 % references to \textit{articles} (with \File{articles.bib} as
608 % bibliography file). For brevity, \File{books.bib} shall
609 % contain entries for just two citation keys: \texttt{ColBenh:93}
610 % and \texttt{Munt:93}, and \File{Articles.bib} shall contain
611 % entries for the two keys \texttt{RouxSmart:95} and
612 % \texttt{Schwind:96}.\footnote{The \File{.bib} files are contained
613 % in the distribution, as well as all the other files mentioned in
614 % the example. So you may have a look at them while reading this,
615 % and run \LaTeX/\BibTeX\ on these files yourself.} Then your
616 % input file might look as shown in
617 % figure~\ref{fig:input} on page~\pageref{fig:input}.
618 %
619 %
620 % To produce a \File{.dvi} file, you'll have to run \LaTeX\ and \BibTeX\ as
621 % follows:\smallskip
622 %
623 % {\small\begin{tabular}{@{}l}
624 % \File{\$ latex sample}\\
625 % \footnotesize \dots\ (\emph{message from \ThisPackage\ to
626 % run Bib\TeX\ on `\File{sample1}' and `\File{sample2}'}) \dots\\
627 % \File{\$ bibtex sample1}\quad
628 % \footnotesize(\emph{Note: Filename without extension!})\\
629 % \File{\$ bibtex sample2}\\
630 % \File{\$ latex sample}\\
631 % \footnotesize\dots\ (\emph{message from \LaTeX: \ErrMessage{Rerun to get references right}}) \dots\\
632 % \File{\$ latex sample}
633 % \end{tabular}}\medskip
634 %
635 % ^^A --- source code for example in next figure ---
636 % \begin{figure}
637 % \centering
638 % \begin{minipage}{.8\textwidth}
639 % \BegRule\par\noindent
640 % \footnotesize
641 % \begin{verbatim}
642 % \documentclass[10pt]{article}
643 % \usepackage{bibtopic}
644 % \begin{document}
645 % \bibliographystyle{alpha}
646 %
647 % \section{Testing}
648 % Let's cite all the books: \cite{ColBenh:93} and
649 % \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
650 %
651 % \begin{btSect}{books}
652 % \section{References from books}
653 % \btPrintCited
654 % \end{btSect}
655 %
656 % \begin{btSect}[plain]{articles}
657 % \section{References from articles}
658 % \btPrintCited
659 %
660 % \section{Articles not cited}
661 % \btPrintNotCited
662 % \end{btSect}
663 % \end{document}
664 % \end{verbatim}
665 % \EndRule
666 % \end{minipage}
667 % \caption[Input file \File{sample.tex}]{Input file \File{sample.tex}\label{fig:input}}
668 % \end{figure}
669 % ^^A ------
670 % ^^A
671 % So there's one extra \File{.aux} file per \Env{btSect}. These
672 % files have the same base name as your \LaTeX\ source file, with
673 % an additional number that refers to the number of the \Env{btSect}
674 % environment in the \LaTeX\ file.\footnote{^^A
675 % You can customize this naming scheme; see the
676 % description of the \Com{thebtauxfile} command,
677 % p.\,\pageref{doc:thebtauxfile}.}
678 % You need to run \BibTeX\ on each of these files.
679 % The resulting \File{.dvi} file should look like
680 % figure~\ref{fig:output} on page~\pageref{fig:output}.
681 %
682 % Some other things to note about this example:
683 % \begin{itemize}
684 % \item The second (the non-optional) argument
685 % of the \Env{btSect} environment specifies
686 % the \BibTeX\ source file(s) for the current `topic'.
687 % \item Every \Env{btSect} may use its own bibliography style
688 % (with some restrictions; see item~\ref{doc:mixing-styles}
689 % on page~\pageref{doc:mixing-styles}).
690 % \item The standard \LaTeX\ command \cmd{\bibliograpy} doesn't work
691 % with \ThisPackage, and is effectively disabled when using the package.
692 % Instead, the package has three separate commands \cmd{\btPrintCited}, \cmd{\btPrintNotCited}
693 % or \cmd{\btPrintAll} to print the citations:
694 % \item \cmd{\btPrintCited}
695 % prints all references for the authors who have been cited in
696 % the document (for the references from \File{articles}, this is
697 % the article by \emph{Roux and Smart}).
698 % \item \cmd{\btPrintNotCited} prints references for authors \emph{not}
699 % cited in the document (\emph{Schwind} in the example).
700 % \item \cmd{\btPrintAll} (not shown in the example) prints all references
701 % from the bibliography file, regardless of whether they have been cited or not.
702 % \item Unless the package option \Env{printheadings} is specified,
703 % the default section titles and running headers of
704 % \Env{thebibliography} are suppressed; the user may provide his
705 % own titles using \LaTeX's normal sectioning commands
706 % (\Com{section} in the example).
707 % \end{itemize}
708 %
709 %
710 % ^^A --- output of example from previous figure ---
711 % \begin{figure}
712 % \centering
713 % \begin{minipage}{.8\textwidth}
714 % \fakesections
715 % \BegRule\par\smallskip\noindent
716 % \footnotesize
717 % \bibliographystyle{alpha}
718 %
719 % \section{Testing}
720 % Let's cite all the books: \cite{ColBenh:93}
721 % and \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
722 %
723 % \begin{btSect}{books}
724 % \section{References from books}
725 % \btPrintCited
726 % \end{btSect}
727 %
728 % \begin{btSect}[plain]{articles}
729 % \section{References from articles}
730 % \btPrintCited
731 %
732 % \section{Articles not cited}
733 % \btPrintNotCited
734 % \end{btSect}
735 % \EndRule
736 % \end{minipage}
737 % \caption[Output from \File{sample.tex}]{Output from \File{sample.tex}}\label{fig:output}
738 % \end{figure}
739 % ^^A ------
740 %
741 % ^^A --------------------------------------------------
742 % \section{User interface}
743 % ^^A --------------------------------------------------
744 % After this short example, let's have a more detailed look on the syntax
745 % of the user commands.
746 %
747 %
748 % ^^A --------------------------------------------------
749 % \subsection{Commands and environments}
750 % ^^A --------------------------------------------------
751 %
752 % \begin{UserCommands}
753 % \item[\cmd{\bibliographystyle}\marg{style}]\SpecialUsageIndex{\bibliographystyle}
754 % This command can be used anywhere (even several times) in the
755 % document to set the default bibliography style \meta{style} for
756 % the subsequent \Env{btSect} environments. Examples for
757 % \meta{style} are \Env{plain}, \Env{named}, \Env{agsm} etc. --
758 % anything for which there exists a \File{.bst} file. (Note that
759 % some bibliography styles are incompatible with each other -- see
760 % item~\ref{doc:mixing-styles} on page~\pageref{doc:mixing-styles}
761 % for more about this.) So this command is quite similar to the standard
762 % \LaTeX\ command with the same name, only that it
763 % can be used several times and that a default \meta{style} (= \Env{plain})
764 % is used if it doesn't occur at all.
765 % The setting
766 % specified by this command can be overridden for specific
767 % \Env{btSect}s by using \Env{btSect}'s optional argument \meta{style}.
768 %
769 % \item[\cmd{\bibliography}\marg{bib-files}]\SpecialUsageIndex{\bibliography}
770 % This command \emph{cannot} be used together with \ThisPackage; in fact, it is disabled
771 % and using it will result in a warning. Instead, use one of the commands \cmd{\btPrintCited},
772 % \cmd{\btPrintNotCited} and \cmd{\btPrintAll} together with the \Env{btSect} environment
773 % (described below).
774 %
775 % \item[\BTbegEnv{btSect}\oarg{style}\marg{bib-files}]^^A
776 % \SpecialEnvIndex{btSect}
777 % This is the main environment of \ThisPackage. It serves as a
778 % `container' for the commands \Com{btPrintCited},
779 % \Com{btPrintNotCited} and \Com{btPrintAll} that actually print
780 % the bibliographies. The environment determines the style and the
781 % \BibTeX\ source file(s) for these references. Its arguments are:
782 %
783 % \begin{itemize}
784 % \item[\meta{style}]
785 % optional argument to override the default
786 % \Env{bibliographystyle} (see the \Com{bibliographystyle}
787 % command) for the scope of the current \Env{btSect}.
788 %
789 % \item[\meta{bib-files}]
790 % the filename(s) of the bibliography file(s) from which the
791 % references for the current \Env{btSect} are taken. Just as in
792 % the standard \Com{bibliography} command of \LaTeX, this
793 % argument consists of one filename or a comma-separated list of
794 % filenames without the \File{.bib} extension.
795 % \end{itemize}
796 % \end{UserCommands}
797 %
798 % The following three commands can only be used inside a \Env{btSect} environment.
799 % They read the \Env{thebibliography} environment
800 % corresponding to the current \meta{bib-files} and print
801 % some or all of the entries in it.
802 %
803 % \begin{UserCommands}
804 % \item[\cmd{\btPrintCited}]\SpecialUsageIndex{\btPrintCited}
805 % Prints all references from \meta{bib-files} that have been cited
806 % within the scope of the current \Env{btUnit} environment (or in
807 % the entire document, if there is no \Env{btUnit} environment --
808 % see the description of the \Env{btUnit} environment below).
809 %
810 % \item[\cmd{\btPrintNotCited}]\SpecialUsageIndex{\btPrintNotCited}
811 % Prints all references from \meta{bib-files} for the citations
812 % occurring in \meta{bib-files} that have \emph{not} been cited in
813 % the current scope.
814 %
815 % \item[\cmd{\btPrintAll}]\SpecialUsageIndex{\btPrintAll}
816 % The union of \Com{btPrintCited} and \Com{btPrintNotCited}: prints
817 % \emph{all} references from \meta{bib-files}, no matter if they
818 % have been cited or not.
819 % \end{UserCommands}
820 %
821 % The following environment provides logically independent citation
822 % sections, i.\,e. it implements the behaviour you would get from
823 % using one of the \Package{chapterbib} or \Package{bibunits}
824 % packages (which are incompatible to \ThisPackage).
825 %
826 % \begin{UserCommands}
827 % \item[\BTbegEnv{btUnit}]\SpecialEnvIndex{btUnit}\label{doc:btUnit}
828 %
829 % Normally, when you invoke one of the
830 % \Com{btPrint\{Cited$\mid$NotCited\}} commands, `cited' means: A
831 % reference that has been cited somewhere in the entire document.
832 % However, if you enclose a part of your document into the
833 % \Env{btUnit} environment, the scope of the citations is
834 % narrowed to this environment. This also means that you can have
835 % several \Env{btUnit}s containing the same bibliographic reference
836 % without getting a \ErrMessage{multiply-defined labels} warning
837 % from \LaTeX.
838 % An example input file using the \Env{btUnit} environment is shown
839 % in figure~\ref{fig:input-btUnit}, p.\,\pageref{fig:input-btUnit}.
840 %
841 % \ImportantNote{When using this environment
842 % \emph{all} of your citations have to occur inside some
843 % \Env{btUnit}. Citations not in the scope of a \Env{btUnit} won't
844 % work at all. Also note that this environment cannot be nested.}
845 %
846 % ^^A --- source code: example using btUnit ---
847 %
848 % \begin{figure}
849 % \centering
850 % \begin{minipage}{.8\textwidth}
851 % \BegRule\par\noindent
852 % \footnotesize
853 % \begin{verbatim}
854 % \documentclass[10pt]{article}
855 % \usepackage{bibtopic}
856 % \begin{document}
857 % \bibliographystyle{alpha}
858 %
859 % \begin{btUnit} %%% begin first btUnit
860 % Let's cite all the books: \cite{ColBenh:93} and
861 % \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
862 %
863 % \begin{btSect}{books}
864 % \section{References from books}
865 % \btPrintCited
866 % \end{btSect}
867 %
868 % \begin{btSect}[plain]{articles}
869 % \section{References from articles}
870 % \btPrintCited
871 %
872 % \section{Articles not cited}
873 % \btPrintNotCited
874 % \end{btSect}
875 % \end{btUnit} %%% end first btUnit
876 %
877 % \begin{btUnit} %%% begin second btUnit
878 % We may cite \cite{RouxSmart:95} another time without causing a
879 % `multiple defined citations' warning from \LaTeX, since this
880 % citation is located in another `btUnit'.
881 %
882 % \begin{btSect}{articles}
883 % \section{All articles}
884 % \btPrintAll
885 % \end{btSect}
886 % \end{btUnit} %%% end second btUnit
887 %
888 % \end{document}
889 % \end{verbatim}
890 % \EndRule
891 % \end{minipage}
892 % \caption[Using the \texttt{btUnit} environment]{Example for using
893 % the \Env{btUnit} environment
894 % (the output isn't shown).\label{fig:input-btUnit}}
895 % \end{figure}
896 %
897 % \end{UserCommands}
898 %
899 % Finally, there's a command for customizing the names of the additional
900 % auxiliary files produced by this package -- i.\,e. the \File{.aux} files
901 % written by \Env{btSect}, and the \File{.bbl} files produced by
902 % running \BibTeX\ on these \File{.aux} files:
903 %
904 % \begin{UserCommands}
905 % \item[\cmd{\thebtauxfile}]
906 % \mbox{}\SpecialUsageIndex{\thebtauxfile}\label{doc:thebtauxfile}^^A
907 % The default definition of this command in \ThisPackage\ looks like this:
908 % \begin{verbatim}
909 % \def\thebtauxfile{\jobname\arabic{btauxfile}}
910 % \end{verbatim}
911 % So the basename of the additional auxiliary files is the
912 % basename of the \LaTeX\ file (\Com{jobname}) with a counter
913 % \Env{btauxfile} appended for uniqueness. This counter is
914 % incremented automatically by each \Env{btSect} environment. This
915 % command may be redefined by the user at any place in the input
916 % file; such a redefinition will then hold for all subsequent
917 % \Env{btSect} environments. For example, the \Env{dot} package
918 % option redefines \Com{thebtauxfile} to include a dot to separate
919 % the filename and the number like this:
920 % \begin{verbatim}
921 % \renewcommand{\thebtauxfile}{\jobname.\arabic{btauxfile}}
922 % \end{verbatim}
923 % Or if you want the package to use uppercase letters instead of
924 % digits, you may redefine \Com{thebtauxfile} in your document
925 % preamble like this:
926 % \begin{verbatim}
927 % \renewcommand{\thebtauxfile}{jobname.\Alph{btauxfile}}
928 % \end{verbatim}
929 %
930 % You may also use any descriptive name for \Com{thebtauxfile}; but
931 % note that if you don't use the built-in counter \Env{btauxfile},
932 % you should double-check that each \Com{thebtauxfile} (for every
933 % \Env{btSect}) does have a unique name; otherwise, a later
934 % auxiliary file with the same name as the current one would overwrite
935 % its contents, and \Package{bibtopic} wouldn't work properly.
936 %
937 % \begin{BackgroundNote}
938 % Also note that virtually any naming scheme may cause conflicts
939 % with existing \File{.aux} files --
940 % e.\,g., \Package{bibtopic} will produce \File{foo1.aux} from
941 % \File{foo.tex}; if there also exists another file named
942 % \File{foo1.tex}, there is a name clash between the regular \File{.aux}
943 % file and the \Package{bibtopic} file. However, this will probably
944 % only lead to serious problems when you're \LaTeX ing the files
945 % \File{foo.tex} and \File{foo1.tex} at the same time, since \TeX\
946 % doesn't lock its auxiliar files, and simultaneous
947 % read\slash write operations to the same file may cause a major mess.
948 % \end{BackgroundNote}
949 %
950 %
951 % \end{UserCommands}
952 %
953 % ^^A --------------------------------------------------
954 % \subsection{Package Options}\label{sec:options}
955 % ^^A --------------------------------------------------
956 % Here is an alphabetical list of all the options of \ThisPackage:
957 %
958 % \begin{description}
959 %
960 % \item[\Env{breakcites}]\BTSpecialOptIndex{breakcites} Since the
961 % \Package{breakcites} package is not compatible with the \Env{btUnit}
962 % definition of \ThisPackage\ (see section~\ref{sec:compatibility}), this
963 % option may be used instead of the package to get the same behaviour.
964 %
965 % \item[\Env{defaultbib}]\mbox{}\BTSpecialOptIndex{defaultbib}\label{doc:defaultbib}
966 % You should use this option as a workaround for the \ErrMessage{unknown bibliography}
967 % error (see item~\ref{doc:unknown-thebibliography} on
968 % page~\pageref{doc:unknown-thebibliography}) in case you don't want to use
969 % some standard package with a `known' definition such as the standard or KOMA classes
970 % or \Package{natbib.sty}.
971 % This option will replace the (current) definition of \Env{thebibliography}
972 % by some built-in default. In this case, a warning is given
973 % since the visual appearance of the bibliography might be different.
974 % This option does nothing if a known definition of \Env{thebibliography} is used.
975 %
976 % \item[\Env{dot}]\BTSpecialOptIndex{dot}^^A
977 % Changes \Com{thebtauxfile} to include an additional dot between the
978 % base file name and the number
979 % (\File{foo.1.}\{\File{aux}$\mid$\File{bbl}\} instead of
980 % \File{foo1.}\{\File{aux}$\mid$\File{bbl}\}; see the description of the
981 % \Com{thebtauxfile} command, p.\,\pageref{doc:thebtauxfile} for
982 % details). This naming scheme was used in the old
983 % \Package{bibtopics.sty}, so you may use the \Env{dot} option for full
984 % compatibility with the old naming scheme.\footnote{The additional
985 % dot was omitted in the current version for compatibility reasons with
986 % certain OSes that don't support multiple dots in filenames.}
987 %
988 % \item[\Env{normalwarnings}]\BTSpecialOptIndex{normalwarnings}
989 % This option turns off the more eye-catching warning about
990 % outdated \BibTeX\ files which is the default for
991 % \ThisPackage. Normally, a command sequence triggering these
992 % warning messages is appended to the \File{.bbl} files
993 % included in the document (so that you can't forget or ignore
994 % the warning which will last until you relly rebuild the
995 % \File{.bbl} file); if you use this option, warning messages
996 % about outdated files (\ErrMessage{Package bibtopic Warning:
997 % xyz.bbl may be outdated}) will appear only for one \LaTeX\
998 % run, and warnings about nonexistant \File{.bbl} files will
999 % look more like the default warnigs (\ErrMessage{Package
1000 % bibtopic Warning: No file sample1.bbl}). The \File{.bbl}
1001 % files are left alone. This option might be used to
1002 % speed up \LaTeX ing and to save disk space with huge
1003 % \File{.bbl} Files.
1004 %
1005 % \item[\Env{overridenumbers/dontoverridenumbers}]^^A
1006 % \BTSpecialOptIndex{overridenumbers}\label{doc:overridenumbers}^^A
1007 % \BTSpecialOptIndex{dontoverridenumbers}^^A
1008 % Some \File{.bst} styles store numbers for the bibliographic
1009 % items in the optional argument of the \Com{bibitem} command,
1010 % in conflict with continuous numbering of the \Com{bibitem}s
1011 % for several \Env{btSect} environments that is the default with
1012 % \ThisPackage. The package tries to catch this and re-activate
1013 % its own counter, issuing a warning message. Using this option
1014 % will disable the overriding behaviour (and the warning).
1015 %
1016 % \item[\Env{printheadings}]\BTSpecialOptIndex{printheadings}^^A
1017 % By default, the normal titles\slash headings for the
1018 % bibliography section (\Com{bibname} or \Com{refname}) are
1019 % suppressed when using \ThisPackage. Use this option to
1020 % print the headings as ususal.
1021 %
1022 % \item[\Env{sectcntreset}]\BTSpecialOptIndex{sectcntreset}
1023 % Reset the numerical label for the bibliography
1024 % items for each \Env{btSect} environment to `1'. (The default
1025 % is continuous numbering.) \ImportantNote{This makes only
1026 % sense when having at most one \Com{btPrintCited} command in
1027 % all your \Env{btSect} environments; otherwise, the citation
1028 % labels in the document won't be unique any more!} The bad
1029 % thing is that you will get {\bfseries no warning} from \LaTeX\
1030 % about \ErrMessage{multiply-defined labels} in this case -- so
1031 % please use this option with care.
1032 %
1033 % \item[\Env{slow}]\BTSpecialOptIndex{slow}
1034 % By default each citation key is saved in the hash table of command sequences
1035 % so that
1036 % it can be checked efficiently by the \Com{btPrint...} commands.
1037 % However, depending on the \TeX\ implementation, the total number of command
1038 % sequences may be limited; e.\,g. for teTeX 0.4, the
1039 % limit is 9500, and in order to raise it, you'd need to recompile the binary.
1040 % TeTeX versions ${}> 0.9$ allow for setting this limit dynamically, as do
1041 % most other implementations (MikTeX, fpTeX).
1042 %
1043 % When using this option, a linear list is used instead the internal hash table;
1044 % this is slower, but will save hash space.
1045 %
1046 % ^^A
1047 % ^^A NOTE: natbib uses a lot of save stack as well, so expect problems
1048 % ^^A when running natbib on huge .bib files (> 1000 entries or so).
1049 % ^^A
1050 %
1051 % \item[\Env{unitcntnoreset}]\BTSpecialOptIndex{unitcntnoreset}
1052 % With this option, the bibitem counter will not be reset for
1053 % for different \Env{btUnit}s (the default behaviour is to reset
1054 % the counter at the beginning of a new \Env{btUnit}).
1055 %
1056 % \item[\Env{verbose}]\BTSpecialOptIndex{verbose}
1057 % Give some messages about the \Com{bibliographystyle} used for
1058 % the current \Env{btSect}, and about \File{.bbl} files being
1059 % marked as outdated. This may be useful if you get confused about which
1060 % bibliography style is active at the moment.
1061 %
1062 % \end{description}
1063 %
1064 %
1065 % ^^A --------------------------------------------------
1066 % \subsection{Warnings and error messages}\label{sec:warnings}
1067 % ^^A --------------------------------------------------
1068 %
1069 % Most of the package-specific warnings should be pretty self-explanatory
1070 % (such as the warning telling you to rerun \BibTeX\ on certain
1071 % files). As for error messages, we have tried to include
1072 % explanatory messages (which can be invoked by typing `\texttt{h}'
1073 % at the error prompt~`\texttt{?}'); most of them will only occur
1074 % under rare circumstances, so we won't explain them here.
1075 % If you get some strange errors that you don't understand, please
1076 % do also have a look at the section `Bugs and Restrictions',
1077 % p.\,\pageref{sec:bugs}.
1078 %
1079 % In what follows, we'll explain some of the more non-obvious warning or
1080 % error messages that you might encounter.
1081 %
1082 % \begin{enumerate}
1083 % \item \ErrMessage{Rerun to get indentation of bibitems right.}\\
1084 % When using multiple bibliographies together with a numerical
1085 % citation style, the item numbering will add up so that the
1086 % space reserved for the items for each separate bibliography
1087 % may be too narrow\CodeRef{ (see the implementation section,
1088 % \Com{bt@adjust@label} }{code:bt@adjust@label}{ for details)}.
1089 % This will break the left-alignment of the bibliography items.
1090 % So we count the number of items printed in the bibliographies
1091 % and use this number to set the items with correct spacing in
1092 % the next run. As for all stuff done via the \File{.aux} file,
1093 % an additional run may be necessary if the information written
1094 % to the \File{.aux} file differs from previous runs; and this
1095 % warning just tells you to do this additional run.
1096 %
1097 % \item \ErrMessage{No appropriate bibitems found for command ... on line ...}\\
1098 % (probably together with an \ErrMessage{Empty `thebibliography' environment}
1099 % warning). This will occur when a \Com{btPrint\dots} command
1100 % tries to read entries that don't exist at all. This may be caused by
1101 % \begin{itemize}
1102 % \item a previous error of some kind (outdated files, e.\,g.); in this case,
1103 % just rerun \BibTeX\slash\LaTeX, and the warnings will disappear.
1104 % \item having included a \Com{btPrintCited} command for a bibliography file
1105 % from which you didn't cite anything at all, or a \Com{btPrintNotCited} command for a
1106 % bibliography all references of which had been cited.
1107 % The command name and the line number included in
1108 % the warning message should help you with pinpointing the command
1109 % that caused this warning.
1110 % The \File{.dvi} file will just contain an empty space where you
1111 % would expect the bibliography; so having separate headings for each
1112 % of the bibliographies should help locating the erroneous command, too.
1113 % \item a \Env{thebibliography} enviroment using an unknown kind of
1114 % \Com{bibitem}s (see also section~\ref{sec:compatibility}
1115 % about compatibility with other packages). You should try
1116 % to switch to another bibliography style in this case (or
1117 % tell us of the incompatibility, if you really want to use
1118 % the same style).
1119 % \end{itemize}
1120 %
1121 % \item \ErrMessage{Found unknown thebibliography environment.}\\
1122 % \label{doc:unknown-thebibliography}^^A
1123 % This message means that the documentclass or some package used in your
1124 % document provides a definition of the
1125 % \Env{thebibliography} environment that \ThisPackage\ cannot handle
1126 % (it has to change the headings, and, more important, parse the
1127 % \Com{bibitem}s).
1128 % The definition is evaluated as late as possible, at the beginning
1129 % of the \Env{btSect} environment; so any package in the preamble
1130 % can influence the definition, regardless if it's loaded before or
1131 % after \ThisPackage.
1132 % Probably the best solution for this problem is to use a `knonw' bibliography
1133 % style (the default or the KOMA classes, or \Package{natbib.sty} should all work).
1134 % If you can't do this,
1135 % you can try to use the \Env{defaultbib} option that will replace the
1136 % offending definition with a built-in default (but it will warn you
1137 % that such a replacement has happened, since the formatting could
1138 % be different from what you would get without that option; see the description of the
1139 % option on page~\pageref{doc:defaultbib} for more on this).
1140 %
1141 % \item \ErrMessage{LaTeX Warning: There were undefined references.}\\
1142 % With the default referencing
1143 % mechanism, you may get this warning when there have been
1144 % changes in the bibliography; but in this case, the warning is always
1145 % followed by another \LaTeX\ warning saying
1146 % \ErrMessage{Label(s) may have changed. Rerun to get
1147 % cross-references right}.\footnote{So whenever this second
1148 % warning does not show up, you know that you have indeed
1149 % undefined references in your document.} However, when you use
1150 % the \Env{btUnit} environment \emph{without} using natbib at the same time,
1151 % this second warning message won't show up (it will be suppressed
1152 % by the definitions that prevent `multiple label' warnings). This means
1153 % that it's best to rerun \LaTeX\ anyway to see if this warning
1154 % message disappears. If it doesn't, then you'll have indeed
1155 % undefined references in your document.
1156 % \end{enumerate}
1157 %
1158 % ^^A --------------------------------------------------
1159 % \subsection{Obsolete Commands}
1160 % ^^A --------------------------------------------------
1161 % \begin{BackgroundNote}
1162 % The commands described in this section were part of the user
1163 % interface of former versions of \Package{bibunits.sty}. Since these
1164 % versions are no longer officially supported, we strongly suggest that you
1165 % don't use these commands for new documents: They don't share some
1166 % of the features of the new commands and are provided for backward
1167 % compatibility only. The descriptions here are intended mainly to help you
1168 % with replacing them with the new commands. \end{BackgroundNote}
1169 %
1170 % \begin{description}
1171 % \item[\normalfont\BTbegEnv{bibunit}\oarg{style}]\SpecialEnvIndex{bibunit}
1172 % Somewhat similar to \Com{btSect}, but the bibliography had to be
1173 % specified by the \Com{putbib} command (which in itself is no
1174 % longer supported, since it had been used exclusively in this
1175 % environment). The actual bibliography was produced with a
1176 % \Com{nocite\Obr*\Cbr} command inside the environment, so the full
1177 % syntax was:\medskip
1178 %
1179 % {\footnotesize\begin{tabular}{@{}l}
1180 % \BTbegEnv{bibunit}\oarg{style} \\
1181 % \Com{nocite}\Obr\Env{*}\Cbr \\
1182 % \Com{putbib}\oarg{bib-files} \\
1183 % \BTendEnv{bibunit}
1184 % \end{tabular}}\medskip
1185 %
1186 % Instead of using these commands, you may now use the \Com{btSect}
1187 % environment like this:\medskip
1188 %
1189 % {\footnotesize\begin{tabular}{@{}l}
1190 % \BTbegEnv{btSect}\oarg{style}\marg{bib-files} \\
1191 % \Com{btPrintAll} \\
1192 % \BTendEnv{btSect} \\
1193 % \end{tabular}}
1194 %
1195 % \item[\normalfont\cmd{\putbib}\oarg{style}]
1196 % See the \Env{bibunit} environment.
1197 %
1198 % \item[\normalfont\BTbegEnv{bibtopics}\marg{style}\marg{bib-files}]\SpecialEnvIndex{bibtopics}
1199 % This command was an alias for the \Env{bibunit} environment above:\medskip
1200 %
1201 % {\footnotesize\begin{tabular}{@{}l}
1202 % \BTbegEnv{bibunit}\oarg{style} \\
1203 % \Com{nocite}\Obr\Env{*}\Cbr \\
1204 % \Com{putbib}\oarg{bib-files} \\
1205 % \BTendEnv{bibunit}
1206 % \end{tabular}}\medskip
1207 %
1208 % It can be replaced with a \Env{btSect} as shown above.
1209 % \end{description}
1210 %
1211 %^^A ========================================
1212 %^^A This probably serves no real purpose at all ...
1213 %^^A ========================================
1214 %^^A ^^A --------------------------------------------------
1215 %^^A \subsection[Referencing bibliography sections (experimental)]{Commands
1216 %^^A for referencing bibliography sections\\ (experimental)}
1217 %^^A ^^A --------------------------------------------------
1218 %^^A
1219 %^^A When you use a named style and you have huge bibliography
1220 %^^A sections, it may be helpful for the reader to know in which
1221 %^^A section he should look for the actual reference. You may want to
1222 %^^A incorporate the section reference directly into the citation, or
1223 %^^A refer to it before or after printing the citation label. For
1224 %^^A these cases, a special command is provided that sets the command
1225 %^^A \Com{btretval} to the reference key of the section containing
1226 %^^A \meta{author-key}:
1227 %^^A \begin{description}
1228 %^^A \item[\normalfont\cmd{\btGetVal}\marg{author-key}]\SpecialUsageIndex{\btGetVal}
1229 %^^A \end{description}
1230 %^^A ^^A
1231 %^^A After calling this command, the command sequence \Com{btretval} will
1232 %^^A contain the value of the section label in which the reference for
1233 %^^A \meta{author-key} had been produced (by some \Com{btPrint\dots} command).
1234 %^^A This section label is
1235 %^^A automatically produced by the \Com{btPrint\dots} commands;
1236 %^^A the section itself should have
1237 %^^A been produced by using some \Com{section} command inside the \Env{btSect}
1238 %^^A environment (see the example in figure~\ref{fig:input}).
1239 %^^A The value contained in \Com{btretval} may then be used to produce
1240 %^^A a reference as usual, e.\,g.:
1241 %^^A \begin{verbatim}
1242 %^^A \ref{\btretval} % or \pageref{\btretval}
1243 %^^A \end{verbatim}
1244 %^^A (You could also use \Com{titleref} command from \Package{titleref.sty}
1245 %^^A to produce references to the section titles themselves.)
1246 %^^A
1247 %^^A For the time being, there is just one user-level frontend to these
1248 %^^A commands; it's quite easy to define your own ones along the lines of this
1249 %^^A example.
1250 %^^A \DescribeMacro{\btCiteSect}\SpecialUsageIndex{\btCiteSect}
1251 %^^A The command \Com{btCiteSect}
1252 %^^A gets the label for citation key |#1| and uses it along with a
1253 %^^A \Com{cite} command. For the example document in figure~\ref{fig:output},
1254 %^^A using the command like this:
1255 %^^A \begin{verbatim}
1256 %^^A ... see, e.\,g. \btCiteSect{ColBenh:93} ...
1257 %^^A \end{verbatim}
1258 %^^A would produce the output:\bigskip
1259 %^^A
1260 %^^A \dots\ see, e.\,g. \cite{ColBenh:93} (section~1)\dots\bigskip
1261 %^^A
1262 %^^A \noindent since the reference from the book by Benhamou and Colmerauer had
1263 %^^A been printed in the references section~1.
1264 %^^A
1265 %^^A This command is simply defined as:
1266 %^^A \begin{verbatim}
1267 %^^A \DeclareRobustCommand\btCiteSect[1]{%
1268 %^^A \btGetVal{#1}%
1269 %^^A \cite{#1} (section~\ref{\btretval})%
1270 %^^A }
1271 %^^A \end{verbatim}
1272 %^^A and can be easily adopted for other purposes. Fancier
1273 %^^A solutions could be implemented using the first optional argument
1274 %^^A of \Package{natbib}'s \Com{cite} command; this way, the reference
1275 %^^A could be integrated into the citation command itself.
1276 %
1277 %^^A \begin{BackgroundNote}
1278 %^^A This feature is still considered experimental, since (as you
1279 %^^A may have gathered from the above description) the user
1280 %^^A interface lacks some elegance \texttt{;-)}. The reason for this is that
1281 %^^A the commands that actually fetch the value of the label for those
1282 %^^A citation keys are not fully expandable\footnote{Because we use
1283 %^^A lists for the key-value pairs, we have to work with \cmd{\def}s
1284 %^^A inside these commands. On the other hand, it seemed to us that
1285 %^^A setting up labels as it is usually done in \LaTeX\ (by defining
1286 %^^A command names) could use up too much of \TeX's string pool (which
1287 %^^A is quite limited on most implementations) for huge
1288 %^^A bibliographies, so we preferred the solution with lists.}, so we
1289 %^^A don't have a command that can be called \emph{inside} a \Com{ref}
1290 %^^A command (expanding to a valid label), which would probably be
1291 %^^A more convenient for the user; hence the roundabout way with
1292 %^^A \Com{btretval}.
1293 %^^A \end{BackgroundNote}
1294 %
1295 %
1296 % ^^A --------------------------------------------------
1297 % \section{Additional .aux files}\label{sec:aux-files}
1298 % ^^A --------------------------------------------------
1299 %
1300 % For bookkeeping purposes, \ThisPackage\ creates up to two extra files (apart
1301 % from the files for each \Env{btSect}):
1302 % \File{btaux.aux} and \File{btbbl.aux}. The names have been chosen
1303 % to minimize conflicts with existing (possibly important) user files;
1304 % to further reduce this danger, \ThisPackage\ adds a short `signature line'
1305 % (a comment) at the beginning of these files when writing them,
1306 % and checks for the presence of this line before overwriting a file.
1307 % If the file is non-empty, but the signature isn't found, an error is raised:
1308 % \ErrMessage{file ... not written by bibtopic}.
1309 % In this case, please check whether the file contains anything
1310 % important, and if so, copy it to a safe place before continuing.
1311 % (Alternatively, you could also rename the file, or move it to a place where \TeX\
1312 % can't find it.)
1313 %
1314 % ^^A --------------------------------------------------
1315 % \section{Compatibility with other packages}\label{sec:compatibility}
1316 % ^^A --------------------------------------------------
1317 %
1318 % The package has been tested with current versions of the
1319 % \textsc{KOMA} classes and current versions of
1320 % \Package{natbib.sty}.\footnote{For \textsc{KOMA} and \Package{natbib.sty},
1321 % the versions tested were 2.5c to 2.9 and 6.8c to 7.0, respectively.}
1322 % Note that just like \ThisPackage\ disables the usual bibliography section
1323 % headings, it will also disable the `hooks' provided by some packages\slash classes,
1324 % e.g. for adding introductory or `preamble' text to the bibliography (e.g. \Com{bibpreamble}
1325 % in \Package{natbib.sty} and current versions of \textsc{KOMA}). Instead
1326 % of using these hooks, such text should be written directly inside the
1327 % \Env{btSect} environment.
1328 %
1329 % In principle, \ThisPackage\ should work with any
1330 % document class or bibliography style, but there are some
1331 % restrictions/exceptions:
1332 % \begin{itemize}
1333 % \item \Package{chapterbib.sty}, \Package{bibunits.sty}: These packages
1334 % implement multiple, logically independent bibliographies.
1335 % Since they do somewhat similar things (and work on the same
1336 % commands) as \ThisPackage, they are both incompatible with
1337 % it. The \Env{btUnit} environment should provide a similar
1338 % functionality, so use this environment instead.
1339 % \item \Package{hyperref.sty}:
1340 % When \Package{hyperref}'s \Env{backref} option
1341 % is used, \ThisPackage\ has to be loaded \emph{after} hyperref.
1342 % (The user is warned if this is not the case.)
1343 % The \Env{backref} option loads the package \Package{backref.sty}, and
1344 % \ThisPackage\ has been tested with \Package{backref.sty} versions
1345 % 1.16 to 1.19 (1999/04/12--2000/01/19).
1346 % \item Packages redefining the \Env{thebibliography} environment in a
1347 % non-standard way: These definitions may cause the parsing
1348 % mechanism of the \Com{bibitems} to fail. See the discussion
1349 % of the \ErrMessage{unknown bibliography} error message
1350 % (item~\ref{doc:unknown-thebibliography} on
1351 % page~\pageref{doc:unknown-thebibliography}) and the \Env{defaultbib}
1352 % option (page~\pageref{doc:defaultbib}) for more about this.
1353 % \item Packages redefining the \Com{@citex} command (like, e.\,g.
1354 % \Package{breakcites}) won't work together with \ThisPackage\
1355 % when the \Env{btUnit} environment is used. Since \ThisPackage\
1356 % redefines \Com{@citex} as late as possible (inside \Env{btUnit}),
1357 % it's most likely that the definitions of the other packages will
1358 % be overwritten. The case with \Package{breakcites.sty} is dealt
1359 % with by the \Env{breakcites} option; if you observe this
1360 % behaviour with other important packages, please email us about
1361 % them.
1362 % \item Packages or \File{.bst} styles using non-standard names for
1363 % bibliography items (other than \Com{bibitem} or
1364 % \Com{harvarditem}). In this case, parsing the \Com{bibitem}s
1365 % will also fail, and will result in an empty bibliography.
1366 % These cases would have to be treated
1367 % explicitly inside \ThisPackage, so if you know of important
1368 % packages that have these non-standard item commands, please email us about
1369 % them.
1370 % \item \Package{harvard.sty}: We withdrew compatibility with this package
1371 % in favour of the current versions of \Package{natbib.sty}
1372 % which has just the same features; so use \Package{natbib} instead.
1373 % \item
1374 % Some \File{.bst}-Styles for numerical styles (e.g.
1375 % \File{plaindin.bst} by K.\,F.\,Lorenzen) incorporate the item number into the
1376 % optional argument of \Com{bibitem}; hence, the internal
1377 % counter won't be used and \ThisPackage\ would not be able to
1378 % manipulate the counter for continuous numbering. \ThisPackage\
1379 % tries to recover in this case by ignoring the optional numerical
1380 % argument and giving a warning.
1381 % This warning can be turned off by using
1382 % one of the package options \Env{overridenumbers} or
1383 % \Env{dontoverridenumbers} (see
1384 % p.\,\pageref{doc:overridenumbers} above).\footnote{Another
1385 % possibility is to change the output function of the
1386 % \File{.bst} file; see the source file \File{bibtopic.dtx},
1387 % lines~\the\inputlineno ff. for an example.}
1388 % \end{itemize}
1389 %
1390 % ^^A
1391 % ^^A The workaround mentioned above:
1392 % ^^A -------------------------------
1393 % ^^A
1394 % ^^A Change the offending \File{.bst} files as follows (of course, you
1395 % ^^A must rename the style when you make such a change): From the
1396 % ^^A function formatting the \Com{bibitem}, delete the stuff
1397 % ^^A formatting the optional argument. Here's an example (from
1398 % ^^A \File{plaindin.bst}). Change this function:
1399 % ^^A
1400 % ^^A FUNCTION {output.bibitem}
1401 % ^^A { newline$
1402 % ^^A "\bibitem[" write$
1403 % ^^A label write$
1404 % ^^A "]{" write$
1405 % ^^A cite$ write$
1406 % ^^A "}" write$
1407 % ^^A newline$
1408 % ^^A ""
1409 % ^^A before.all 'output.state :=
1410 % ^^A }
1411 % ^^A
1412 % ^^A into:
1413 % ^^A
1414 % ^^A FUNCTION {output.bibitem}
1415 % ^^A { newline$
1416 % ^^A "\bibitem{" write$
1417 % ^^A cite$ write$
1418 % ^^A "}" write$
1419 % ^^A newline$
1420 % ^^A ""
1421 % ^^A before.all 'output.state :=
1422 % ^^A }
1423 % ^^A
1424 %
1425 % ^^A --------------------------------------------------
1426 % \section{Bugs and Restrictions}\label{sec:bugs}
1427 % ^^A --------------------------------------------------
1428 %
1429 %
1430 % \begin{enumerate}
1431 % \item
1432 % \BibTeX's cross-referencing doesn't work between items in different
1433 % \Env{btSect}s. Since \BibTeX\ is run separately on the files corresponding
1434 % to different \Env{btSect}s, it won't be able to resolve the cross-reference.
1435 %
1436 % \item
1437 % When the bibliography files have several items with the same author and
1438 % the same year, they are tagged with `a', `b', `c' etc. extensions even if
1439 % not all of them are cited.
1440 % When the bibliography is printed with \Com{btPrintCited}, funny
1441 % effects might occur, e.g. a bibliography where only a `b' item is shown.
1442 %
1443 % \item
1444 % \ThisPackage\ doesn't work with the `unsorted' citation
1445 % styles\label{sec:unsorted} such as \File{unsrt} or
1446 % \File{unsrtdin}.\footnote{^^A
1447 % \ThisPackage\ writes global \Com{citation}\Obr\Env{*}\Cbr\
1448 % commands to its additional \File{.aux} files: When
1449 % constructing the \File{.aux} file we don't know in which of
1450 % the possibly several \File{.bib} files some citation will
1451 % occur. So since there are no specific \Com{citation} commands
1452 % in the (additional) \File{.aux} files, \BibTeX\ can only apply
1453 % author-year sorting or print the items in the order they
1454 % appear in the \File{.bib} file.} Use the package
1455 % \Package{multibib.sty} instead (see also section~\ref{sec:related-packages}).
1456 %
1457 % \item
1458 % \ThisPackage\ is case sensitive, while \BibTeX\ isn't. That means that
1459 % while \BibTeX\ treats a \File{.bib} entry like:\par
1460 % \begin{tabular}{@{}l}
1461 % |@article{Gnus:98,| \dots\\
1462 % \end{tabular}\par
1463 % and a citation |\cite{gnus:98}| as the same key, \ThisPackage\
1464 % treats them as different keys, and you will get an
1465 % \ErrMessage{undefined reference} error for the citation command.\footnote{The reason
1466 % for this restriction is that \BibTeX\ reads the
1467 % \Com{citation} labels when reading the \File{.aux} file and
1468 % writes out the keys for the \Com{bibitem} commands it produces
1469 % accordingly. However, bibtopic only writes a
1470 % \Com{citation}\Obr\Env{*}\Cbr\ to the \File{.aux} file, so
1471 % \BibTeX\ can't access these labels and therefore has to use
1472 % the spelling from the \File{.bib} file.}
1473 %
1474 % \item \mbox{}\label{doc:mixing-styles}^^A
1475 % When mixing several citation styles, it's important to know that
1476 % numerical citation styles and author-year styles are generally
1477 % \emph{incompatible} with each other. This means that the style
1478 % declared first will always override later re-declarations, since it is
1479 % globally set at the begin of the document and can't be changed
1480 % afterwards. Examples for numerical styles in that sense are
1481 % \Env{plain} and \Env{alpha} (even if the name doesn't sound like it),
1482 % examples for author-year styles are the `harvard' styles \Env{agsm}
1483 % and \File{dcu} or the \Env{authordate1-4} style. As for these
1484 % examples, you may mix \Env{alpha} with \Env{plain}, but not with
1485 % \Env{agsm} or vice versa.
1486 %
1487 % \item
1488 % Having the same reference in several bibliographies in the
1489 % same \Env{btUnit} (e.\,g., when using both the \Com{btPrintCited}
1490 % and the \Com{btPrintAll} command to print parts of the same
1491 % \Env{thebibliography} twice) may lead to problems with
1492 % labelling:
1493 %
1494 % With the numerical or `plain' labelling styles, such multiple
1495 % references are treated as \emph{different keys}, i.e. they
1496 % receive different numbers.
1497 %
1498 % With \Package{natbib.sty}, things are a bit different: Multiple
1499 % references will get the same number; but the numbering will
1500 % have \emph{gaps} since the repeated entries will be assigned the
1501 % number of the \emph{last} \Com{bibcite} enty of the \File{.aux}
1502 % file of that repeated entry. You will also get warnings
1503 % about \ErrMessage{multiply defined citations}, and the warning
1504 % \ErrMessage{Rerun to get citations correct} will appear after each
1505 % \LaTeX\ run.
1506 %
1507 % The latter problem can be avoided by switching to alphabetical or
1508 % author-year styles, but the warnings about \ErrMessage{multiply
1509 % defined citations} will remain. To get rid of these, you would need
1510 % to use \Env{btUnit}s and put the \Com{btPrintAll} and the
1511 % \Com{btPrintCited} command into different \Env{btUnit}s (see
1512 % figure~\ref{fig:input-btUnit} on page~\pageref{fig:input-btUnit}
1513 % for an example).
1514 %
1515 %
1516 %^^A \item
1517 %^^A Sometimes, \BibTeX\ is putting \Com{newcommand}s into the
1518 %^^A \File{.bbl} file; if you input such a file several times, \LaTeX\
1519 %^^A will give the error message \ErrMessage{Command xyz already
1520 %^^A defined}. Currently the only workaround is to change the
1521 %^^A \Com{newcommand} manually to a \Com{renewcommand} or (even
1522 %^^A better) to a \Com{providecommand} in the \File{bbl} file.
1523 %
1524 % \item
1525 % Switching from one bibliographic style file to another may cause
1526 % compiling errors (due to the outdated \File{.aux} and \File{.bbl}
1527 % files). Try to make \LaTeX\ ignore these errors by
1528 % responding~`\texttt{r}' after the help prompt~`\texttt{?}' (don't
1529 % quit with~`\texttt{x}', because you want the \File{.aux} file to
1530 % be regenerated); if all fails, delete the \File{.aux} and
1531 % \File{.bbl} files before the next \LaTeX\ run.
1532 %
1533 % \item
1534 % Brackets in the \File{.bib} file: The brackets `\Env{[]}' are
1535 % special to \LaTeX\ in that they denote the bounds of an optional
1536 % argument, and \Com{bibitem} uses such an optional argument
1537 % for the item labels. Therefore using brackets `\Env{[...]}' in
1538 % a \File{.bib} file entry which is used for sorting may mangle
1539 % the \Com{bibitem} command. In this case, hide the brackets from
1540 % \LaTeX\ by enclosing them in another pair of braces, like this:
1541 % `\verb|{[...]}|'. (\ThisPackage\ will try to detect such misleading
1542 % brackets an warn you about them.)
1543 % \end{enumerate}
1544 %
1545 % ^^A --------------------------------------------------
1546 % \section{If you're not a user of \BibTeX\ \dots}
1547 % ^^A --------------------------------------------------
1548 %
1549 % \dots\ (which would be a pity, though), the feature of
1550 % selecting only those items actually cited in the document might
1551 % come in handy: All you'll have to do is provide a sorted
1552 % \Env{thebibliography}, and \ThisPackage\ will be able to select
1553 % the needed citations. The
1554 % easiest way to use this is to put your \Env{thebibliography}
1555 % environment into a separate file (call it \File{mybib.bbl}) that
1556 % can be included using the standard \Env{btSect} environment like,
1557 % e.\,g.:
1558 %
1559 % {\footnotesize
1560 % \begin{verbatim}
1561 % \renewcommand{\thebtauxfile}{mybib}
1562 % \begin{btSect}{}
1563 % \btPrintCited
1564 % \end{btSect}
1565 % \end{verbatim}}
1566 % ^^A
1567 % In this case, the second argument of \Env{btSect} serves no
1568 % purpose and may as well be left blank. It'll be also a good
1569 % idea to turn off persistent warnings from \ThisPackage\ by using
1570 % the \Env{normalwarnings} option -- else, an additional `warning
1571 % line' might be appended to your \File{mybib.bbl} in the first
1572 % \LaTeX\ run: \ThisPackage\ will realize that the \File{.aux} file
1573 % has changed\CodeRef{ (see the implementation section,
1574 % \Com{bt@cmp} }{code:bt@if@files@differ}{ for details)}, and it will tell you
1575 % to rerun \BibTeX\ to update your \File{.bbl} File. {\bfseries
1576 % Don't do that:} Running \BibTeX\ as advertised would overwrite
1577 % your handwritten \File{.bbl} file with an \emph{empty}
1578 % bibliography! With the \Env{normalwarnings} option, this message
1579 % won't occur; otherwise, you'd have to delete the `warning' line
1580 % from \File{mybib.bbl} manually in order to get rid of these
1581 % recurrent warnings.
1582 %
1583 % ^^A --------------------------------------------------
1584 % \section[Other useful tools]{Other tools that might be useful with\\ \ThisPackage}\label{sec:tools}
1585 % ^^A --------------------------------------------------
1586 %
1587 % You'll probably need to split up your exitsting \File{.bib}
1588 % file(s) when switching to \ThisPackage. This section lists
1589 % some utilities that might be useful for this task. Some of these
1590 % tools can be used for other purposes, too -- like sorting,
1591 % merging, consistency checks, automatic key generation etc.; but
1592 % here we'll concentrate on the extraction issue only.
1593 %
1594 % Note that if you want to keep all your references together in one
1595 % master \File{.bib} file, you can always use a dummy attribute
1596 % that will be ignored by \BibTeX\ but may be used as a key for
1597 % selecting entries with one of the tools mentioned here.
1598 %
1599 % \begin{itemize}
1600 % \item
1601 % \textsc{BibTool} (available as C source code on CTAN:
1602 % \url{biblio/bibtex/utils/bibtool/}). It allows you to
1603 % specify regular expressions for extracting entries from a
1604 % \File{.bib} file. For example, the following command extracts
1605 % all `online documents' (items containing the string
1606 % \Env{http:} or \Env{ftp:} in any field) from \File{mybib.bib}
1607 % and writes them to a newly created bibliography file
1608 % \File{online.bib} (the single quotes are needed with some Unix
1609 % shells to prevent unwanted expansion of braces):\par
1610 % \begin{tabular}{@{}l}
1611 % |bibtool -- 'select{"[hf]t?tp:"}' mybib.bib -o online.bib|
1612 % \end{tabular}
1613 % \item
1614 % btOOL (C\slash Perl library, available from:
1615 % \url{biblio/bibtex/utils/btOOL/}; more documentation can be
1616 % obtained from the author's home page:
1617 % \url{http://starship.python.net/~gward/btOOL/}). A powerful
1618 % library for writing Perl scripts that manipulate \File{.bib}
1619 % files. Very flexible, but requires Perl programming skills.
1620 % \item
1621 % \File{bibextract} (shell and awk scripts, available from:
1622 % \url{biblio/bibtex/utils/bibextract/}). Similar to
1623 % \textsc{BibTool}, it lets you use regular expressions to extract
1624 % entries from a \File{.bib} file. With \File{bibextract}, the
1625 % example above would look like this:\par
1626 % \begin{tabular}{@{}l}
1627 % |bibextract "" "[hf]t?tp:" mybib.bib > online.bib|
1628 % \end{tabular}
1629 % \end{itemize}
1630 %
1631 % ^^A --------------------------------------------------
1632 % \section{Related Packages}\label{sec:related-packages}
1633 % ^^A --------------------------------------------------
1634 %
1635 % There are several packages with a similar purpose as \ThisPackage:
1636 %
1637 % \begin{description}
1638 % \item[\Package{multibib.sty}:] This package provides similar
1639 % functionality as \Package{bibtopic}, but with a different approach
1640 % for the user interface: Instead of splitting up the \File{.bib} files,
1641 % you use different, bibliography-specific citation commands.
1642 % In contrast to \ThisPackage,
1643 % \Package{multibib.sty} can also deal with `\texttt{unsorted}'
1644 % bibliography styles (see page~\pageref{sec:unsorted} above).
1645 %
1646 % \item[\Package{chapterbib.sty}, \Package{bibunits.sty}:]
1647 % These provide multiple bibliographies as well;
1648 % the main difference is that with these packages different
1649 % parts of a document can have their own dedicated bibliography
1650 % which is independent from the other bibliographies, whereas
1651 % \Package{bibtopic}\slash\Package{multibib}
1652 % provide a global bibliography divided into
1653 % sections.
1654 %
1655 % \item[\Package{Camel}:]
1656 % Along with many powerful additional features, this larger package also
1657 % contains macros for sectioned bibliographies; the
1658 % user interface is quite different from standard
1659 % \LaTeX\ (e.\,g., the \Com{cite} command is replaced by a
1660 % \Com{source} command).
1661 % \end{description}
1662 %
1663 % ^^A --------------------------------------------------
1664 % ^^A Place to stop if implementation shouldn't be printed
1665 % ^^A --------------------------------------------------
1666 %
1667 % \StopEventually{\relax}
1668 % \writeauxfile{\string\gdef\string\implementation{Y}}
1669 %
1670 % ^^A --------------------------------------------------
1671 % \section{Implementation}\label{sec:sourcecode}
1672 % ^^A --------------------------------------------------
1673 %
1674 % Some conventions: All commands in this package use the prefix `\Env{bt}' to identify them
1675 % as belonging to \ThisPackage. Internal commands are prefixed with
1676 % `\Env{\mbox{bt@}}'; ^^A don't hyphenate this one ...
1677 % user interface commands use mixed upper-/lowercase letters.
1678 % (After the fact I heard these were reserved for the \LaTeX\ API, so maybe
1679 % this wasn't such a brilliant idea after all. It's too late to change it now,
1680 % however ...)
1681 % Numbers in square brackets
1682 % (like `\ShowCodeRef{136}') refer to the line numbers on the left margin.
1683 %
1684 % Parts tagged with the \Module{debug} flag are included in debugging
1685 % versions only; production versions will not contain these parts.
1686 %
1687 % \begin{macrocode}
1688 %<*package>
1689 % \end{macrocode}
1690 % 1996/12/01 is the oldest \LaTeX\ version with which this package has been tested.
1691 % \begin{macrocode}
1692 \NeedsTeXFormat{LaTeX2e}[1996/12/01] \ProvidesPackage{bibtopic}[2006/09/08 v1.1a
1693 Sectioned Bibliographies]
1694 % \end{macrocode}
1695 %
1696 % ^^A --------------------------------------------------
1697 % \subsection{Some help commands}
1698 % ^^A --------------------------------------------------
1699 %
1700 % \begin{macro}{\bt@debug}
1701 % Uncommenting the \Com{@debug@true} line will
1702 % log all the debugging messages to the terminal.
1703 % You may also log only selected messages by
1704 % specifying an optional argument to any of the
1705 % \Com{bt@debug} commands in the style file itself.
1706 % The debugging code is only included when \File{docstrip}
1707 % is run with the \Env{debug} option specified.
1708 % \begin{macrocode}
1709 %<*debug>
1710 \newif\bt@ifdebug
1711 %%% \bt@debugtrue % uncomment this line to activate global debugging
1712 \newcommand*\bt@debug[2][]{%
1713 \bt@ifdebug
1714 \PackageInfo{bibtopic}{#1}%
1715 \typeout{DBG: #2}%
1716 \else
1717 \ifx#1\@empty\else
1718 \typeout{DBG (#1): #2}%
1719 \fi
1720 \fi
1721 }
1722 %</debug>
1723 % \end{macrocode}
1724 % \end{macro}
1725 % \Package{ifthen.sty} is needed for many \Com{ifthenelse} constructs. It uses
1726 % the scratch commands \Com{@tempa} etc. frequently, so we define our own scratch
1727 % commands as to not interfere with these.
1728 % \begin{macrocode}
1729 \RequirePackage{ifthen}
1730 \newcommand\bt@tempa{}
1731 \newcommand\bt@tempb{}
1732 \newcommand\bt@tempc{}
1733 \newcommand\bt@args{}
1734 % \end{macrocode}
1735 % \begin{macro}{\bt@info}
1736 % \begin{macro}{\bt@infoNoLine}
1737 % Macros for less important messages that should only
1738 % be printed when the package option \Env{verbose} is set (see there,
1739 % \CodeRef{}{code:verbose}{}).
1740 % \begin{macrocode}
1741 \newcommand*\bt@info{\@gobble}
1742 \newcommand*\bt@infoNoLine{\@gobble}
1743 % \end{macrocode}
1744 % \end{macro}
1745 % \end{macro}
1746 %
1747 % \begin{macro}{\bt@gobblethree}
1748 % Analogous to \LaTeX's \Com{@gobbletwo}.
1749 % \begin{macrocode}
1750 \newcommand\bt@gobblethree[3]{}
1751 % \end{macrocode}
1752 % \end{macro}
1753 %
1754 %
1755 % ^^A --------------------------------------------------
1756 % \subsection{Allocations}
1757 % ^^A --------------------------------------------------
1758 % \subsubsection{Booleans}
1759 % ^^A --------------------------------------------------
1760 % Check for \Package{natbib.sty}:
1761 % \begin{macrocode}
1762 \newif\ifbt@natbib
1763 % \end{macrocode}
1764 % Check for presence of one of the \Package{scr*} classes (aka KOMA):
1765 % \begin{macrocode}
1766 \newif\ifbt@koma@class
1767 % \end{macrocode}
1768 % Switch to deal with the `backref' option of \Package{hyperref.sty}:
1769 % \begin{macrocode}
1770 \newif\ifbt@brf
1771 \newif\ifbt@after@brf
1772 % \end{macrocode}
1773 % A global switch that says that a given element is in a list
1774 % (set by \Com{bt@testelem}, used e.\,g. in \Com{bt@add@elem}):
1775 % \begin{macrocode}
1776 \newif\ifbt@elem
1777 % \end{macrocode}
1778 % Switch for error checking inside the \Env{btSect} environment:
1779 % \begin{macrocode}
1780 \newif\ifbt@inside@sect
1781 % \end{macrocode}
1782 % Switch for error checking inside the \Env{btUnit} environment:
1783 % \begin{macrocode}
1784 \newif\ifbt@inside@unit
1785 % \end{macrocode}
1786 % The following three switches are used along with \Com{bt@call@item}.
1787 % First a flag for checking if any items have been found at all:
1788 % \begin{macrocode}
1789 \newif\ifbt@found@item
1790 % \end{macrocode}
1791 % True if we have to print only the cited items:
1792 % \begin{macrocode}
1793 \newif\ifbt@print@cited
1794 % \end{macrocode}
1795 % True if we have to print all items (needed if we
1796 % parse the items for the keyval stuff):
1797 % \begin{macrocode}
1798 \newif\ifbt@print@all
1799 % \end{macrocode}
1800 % Switch for compatibility with older versions of
1801 % \Package{bibtopics} (may be set inside the document):
1802 % \begin{macrocode}
1803 \newif\if@globalbiblio
1804 % \end{macrocode}
1805 %
1806 % ^^A --------------------------------------------------
1807 % \subsubsection{Counters etc.}
1808 % ^^A --------------------------------------------------
1809 %
1810 % Since \TeX\ is notoriously short of count registers, most of the counters used
1811 % are no real counters, but command sequences holding integer values.
1812 % Here's a command to globally increment such a fake counter:
1813 % \begin{macro}{\bt@stepcnt}
1814 % \begin{macrocode}
1815 \newcommand\bt@stepcnt[1]{%
1816 \@tempcnta#1
1817 \advance\@tempcnta\@ne
1818 \protected@xdef#1{\the\@tempcnta}%
1819 }
1820 % \end{macrocode}
1821 % \end{macro}
1822 % ^^A
1823 % This is the only `real' counter: \Env{btauxfile} is the current number of the
1824 % \Env{btSect} environment; the representation \Com{thebtauxfile} is the full basename
1825 % of the \File{.aux} and {.bbl} files to be used. (It's a real counter to make it
1826 % easier for users to redefine \Com{thebtauxfile}.)
1827 % \begin{macrocode}
1828 \newcounter{btauxfile}
1829 \def\thebtauxfile{\jobname\arabic{btauxfile}}
1830 % \end{macrocode}
1831 % To produce more than one citation list (if there's more than one \Env{btUnit}),
1832 % \Com{bt@unit@cnt} is appended to the listname \Com{bt@sect} (see the command
1833 % \Com{reset@bt@sect}). It is initialized with 1 here:
1834 % \begin{macrocode}
1835 \newcommand\bt@unit@cnt{1}
1836 % \end{macrocode}
1837 % Numbering used for the labeling commands by the keyval stuff:
1838 % \begin{macrocode}
1839 \newcommand\bt@internal@sect@cnt{0}
1840 % \end{macrocode}
1841 % Number of all bibitems seen so far (possibly in sevaral
1842 % \Env{btUnit}s):
1843 % \begin{macrocode}
1844 \newcommand\bt@helpctr{0}
1845 % \end{macrocode}
1846 % Total number of bibitems in \emph{all} bibliographies,
1847 % read from the \File{.aux} file:
1848 % \begin{macrocode}
1849 \newcommand\bt@totalctr{0}
1850 % \end{macrocode}
1851 %
1852 % ^^A --------------------------------------------------
1853 % \subsubsection{Filehandles}
1854 % ^^A --------------------------------------------------
1855 % \begin{macrocode}
1856 \newread\bt@infilea
1857 \newread\bt@infileb
1858 \newwrite\bt@outfile
1859 % \end{macrocode}
1860
1861 % ^^A --------------------------------------------------
1862 % \subsection{Package options}\label{sec:PackageOptions}
1863 % ^^A --------------------------------------------------
1864 %
1865 % \Option{btunits}\label{code:btunits}^^A
1866 % This option is obsolete and defined here only for backwards compatibility.
1867 % \begin{macrocode}
1868 \newif\ifbt@btunits
1869 \DeclareOption{btunits}{%
1870 \PackageWarningNoLine{bibtopic}{ignoring obsolete `btunits' option}
1871 }
1872 % \end{macrocode}
1873 %
1874 % \Option{defaultbib}
1875 % Option to ignore `unknown thebibliography' errors by providing
1876 % a fallback definition.
1877 % \begin{macrocode}
1878 \newif\ifbt@fallback@thb
1879 \DeclareOption{defaultbib}{%
1880 \global\bt@fallback@thbtrue
1881 }
1882 % \end{macrocode}
1883 %
1884 % \Option{verbose}
1885 % This option makes the \Com{bt@info} messages appear on the screen. We
1886 % just change the meaning of \Com{bt@info} and \Com{bt@infoNoLine} from the
1887 % default \Com{@gobble} to the verbose behaviour.
1888 % \begin{macrocode}
1889 \DeclareOption{verbose}{% +code:verbose;
1890 \def\bt@info#1{%
1891 \begingroup
1892 \def\MessageBreak{^^J(bibtopic)\@spaces\@spaces\@spaces}%
1893 \set@display@protect
1894 \immediate\write\@unused{%
1895 ^^JPackage bibtopic info: #1\on@line.^^J%
1896 }%
1897 \endgroup
1898 }%
1899 \def\bt@infoNoLine#1{%
1900 \begingroup
1901 \def\MessageBreak{^^J(bibtopic)\@spaces\@spaces\@spaces}%
1902 \set@display@protect
1903 \immediate\write\@unused{%
1904 ^^JPackage bibtopic info: #1.^^J%
1905 }%
1906 \endgroup
1907 }%
1908 }
1909 % \end{macrocode}
1910 %
1911 % \Option{breakcites}
1912 % This option can be used instead of including the \Package{breakcites} package,
1913 % which is incompatible to \ThisPackage\ if the \Env{btUnit} environment
1914 % is used.
1915 % \begin{macrocode}
1916 \newif\ifbt@breakcites
1917 \DeclareOption{breakcites}{%
1918 \global\bt@breakcitestrue
1919 }
1920 % \end{macrocode}
1921 % ^^A
1922 % \Option{normalwarnings}
1923 % Option for not hard-coding warnings in the .bbl files;
1924 % this will make the warnings to rerun \BibTeX\ only appear once.
1925 % Useful if you don't want to have your .bbl files modified.
1926 % \begin{macrocode}
1927 \newif\ifbt@normalwarnings
1928 \DeclareOption{normalwarnings}{%
1929 \global\bt@normalwarningstrue
1930 }
1931 % \end{macrocode}
1932 % ^^A
1933 % \Option{printheadings}\label{code:printheadings}
1934 % Don't suppress the default bibliography headings (suppressing them
1935 % is the default).
1936 %
1937 % \begin{macrocode}
1938 \newif\ifbt@printheadings
1939 \DeclareOption{printheadings}{%
1940 \global\bt@printheadingstrue
1941 }
1942 % \end{macrocode}
1943 % ^^A
1944 % \Option{unitcntnoreset}
1945 % Option to not reset the bibitem counter for new \Env{btUnit}s:
1946 % \begin{macrocode}
1947 \newif\ifbt@part@cont@ctr
1948 \DeclareOption{unitcntnoreset}{%
1949 \global\bt@part@cont@ctrtrue
1950 }
1951 % \end{macrocode}
1952 %
1953 % ^^A
1954 % \Option{sectcntreset}
1955 % Option to reset the bibitem counter for new \Env{btUnit}s:
1956 % \begin{macrocode}
1957 \newif\ifbt@sectctr@reset
1958 \DeclareOption{sectcntreset}{%
1959 \global\bt@sectctr@resettrue
1960 }
1961 % \end{macrocode}
1962 %
1963 % ^^A
1964 % \Option{slow}
1965 % Option to select bibitems by linear search in a list of keys instead of
1966 % hashing on the keys.
1967 % \begin{macrocode}
1968 \newif\ifbt@fast
1969 \bt@fasttrue
1970 \DeclareOption{slow}{%
1971 \global\bt@fastfalse
1972 }
1973 % \end{macrocode}
1974 %
1975 % ^^A
1976 % \Option{dot}
1977 % Compatibility with earlier versions: separate the counter from the file
1978 % name in additional files by a dot.
1979 % \begin{macrocode}
1980 \DeclareOption{dot}{%
1981 \def\thebtauxfile{\jobname.\arabic{btauxfile}}%
1982 }
1983 % \end{macrocode}
1984 % \Option{overridenumbers}
1985 % Ignore the numbering in the optional argument of \Com{bibitem} (default
1986 % is to warn in this case).
1987 % \begin{macrocode}
1988 \newif\ifbt@warn@override
1989 \bt@warn@overridetrue
1990 \newif\ifbt@override@numargs
1991 \bt@override@numargstrue
1992 \newif\ifbt@overridden@numargs
1993 \DeclareOption{overridenumbers}{%
1994 \bt@warn@overridefalse
1995 \bt@override@numargstrue
1996 }
1997 % \end{macrocode}
1998 % \Option{dontoverridenumbers}
1999 % \emph{Don't} ignore the numbering in the optional argument of
2000 % \Com{bibitem} (opposite of previous option; default is to warn
2001 % in this case).
2002 % \begin{macrocode}
2003 \DeclareOption{dontoverridenumbers}{%
2004 \bt@warn@overridefalse
2005 \bt@override@numargsfalse
2006 }
2007 % \end{macrocode}
2008 %
2009 % \begin{macrocode}
2010 \ProcessOptions*
2011 % \end{macrocode}
2012
2013 % ^^A --------------------------------------------------
2014 % \subsection{Commands}
2015 % ^^A --------------------------------------------------
2016 % ^^A
2017 %
2018 % \begin{macro}{\bt@isnum}
2019 % Check if the argument is a number; evaluate the second argument if so;
2020 % evaluate the third argument if not. The \Com{ifnum} trick is by D. Arseneau,
2021 % \url{<[email protected]>}):
2022 % \begin{macrocode}
2023 \newcommand\bt@isnum[1]{%
2024 \if!\ifnum9<1#1!\else_\fi
2025 \expandafter\@firstoftwo
2026 \else
2027 \expandafter\@secondoftwo
2028 \fi
2029 }
2030 % \end{macrocode}
2031 % \end{macro}
2032
2033 % \begin{macro}{\bt@sect@ref@list}
2034 % A list of authors referenced in a \Env{btSect}. Used by the
2035 % keyval stuff (see
2036 % \Com{btSect} \CodeRef{}{code:bt@sect@ref@listReset}{}
2037 % and \Com{bt@do@print@item} \CodeRef{}{code:bt@sect@ref@listAdd}{}).
2038 % \begin{macrocode}
2039 \newcommand*\bt@sect@ref@list{}
2040 % \end{macrocode}
2041 % \end{macro}
2042 % \begin{macro}{\bt@curr@cmd}
2043 % Macro to save the user command that led to an `empty
2044 % thebibliography' error (used in \Com{bt@bibitemcheck}, see
2045 % \CodeRef{}{code:bt@curr@cmd}{}; this is set by
2046 % the \Com{btPrint...} commands.
2047 % \begin{macrocode}
2048 \newcommand\bt@curr@file{}
2049 % \end{macrocode}
2050 % \end{macro}
2051 % \begin{macro}{\bt@curr@line}
2052 % Save line number of \Com{bt@curr@cmd} for later use (used with previous macro).
2053 % \begin{macrocode}
2054 \newcommand\bt@curr@line{}
2055 % \end{macrocode}
2056 % \end{macro}
2057 % \begin{macro}{\bt@kv@req@list}
2058 % List to save keys that have been requested by the keyval
2059 % user commands; only those keys will be written
2060 % to \Com{bt@sect@ref@list}.
2061 % \begin{macrocode}
2062 \newcommand*\bt@kv@req@list{}
2063 % \end{macrocode}
2064 % \end{macro}
2065
2066 % \begin{macro}{\bt@curr@bib@file}
2067 % Store the name of the current \File{.bib} file; needed in error message.
2068 % \begin{macrocode}
2069 \newcommand*\bt@curr@bib@file{}
2070 % \end{macrocode}
2071 % \end{macro}
2072 % ^^A
2073 % \begin{macro}{\bt@cited@list}
2074 % List of all cited authors. Accessed by \Com{btPrintCited} and
2075 % \Com{btPrintNotCited} to check if a given author has been cited.
2076 % \begin{macrocode}
2077 \newcommand*\bt@cited@list{}
2078 % \end{macrocode}
2079 % \end{macro}
2080 % ^^A
2081 % \begin{macro}{\bt@warn@files}
2082 % List of \File{.bbl} files (needed in warnings); see e.\,g. \Com{bt@files@warnings},
2083 % section~\ref{sec:PackageWarnings}, p.\,\pageref{sec:PackageWarnings}
2084 % \begin{macrocode}
2085 \newcommand*\bt@warn@files{}
2086 % \end{macrocode}
2087 % \end{macro}
2088 % ^^A
2089 % For saving the first argument of \Env{thebibliography};
2090 % possibly modified (for width correction) and used in calls to \Com{bt@savebib}:
2091 % \begin{macrocode}
2092 \newcommand*\bt@label{}
2093 % \end{macrocode}
2094 % ^^A
2095 % \begin{macro}{\bt@globalstyle}
2096 % \begin{macro}{\bt@defaultstyle}
2097 % The global bibliographystyle selected by \Com{bibliographystyle};
2098 % defaults to \Com{bt@defaultstyle} if none is selected:
2099 % \begin{macrocode}
2100 \newcommand*\bt@globalstyle{}%
2101 \newcommand*\bt@defaultstyle{plain}%
2102 % \end{macrocode}
2103 % \end{macro}
2104 % \end{macro}
2105 % We'll redefine the \Com{citation} command to add its argument (the citation key)
2106 % to a list of references (\Com{bt@cited@list}).\footnote{Maybe one could have used
2107 % \Com{@ifundefined\Obr b@\bslash @citeb \bslash extra@b@citeb\Cbr} instead, but the list thing seemed
2108 % more straightforward.} First we save the original meaning of \Com{citation} in
2109 % \Com{@bt@oldcitation} (it's just \Com{@gobble} in standard \LaTeX, and evaluated
2110 % only by \BibTeX, but who knows \dots):
2111 % \begin{macrocode}
2112 \newcommand*\@bt@orig@citation{}
2113 %<debug>\bt@debug{saving meaning of \string\citation : \meaning\citation}%
2114 \let\@bt@orig@citation\citation
2115 % \end{macrocode}
2116 % ^^A
2117 % \begin{macro}{\citation}
2118 % This command is redefined to add its argument (the citation key) to
2119 % a list of keys (specific to the current \Com{btUnit}). Definine
2120 % the command separately for each case (a slight optimization avoiding
2121 % to branch on the \Env{@bt@fast} option each time it is called).
2122 % \begin{macrocode}
2123 \ifthenelse{\boolean{bt@fast}}{%
2124 \def\citation#1{%
2125 \@for\bt@tempa:=#1\do{%
2126 \def\@extra@b@citeb{\bt@unit@cnt}%
2127 % \end{macrocode}
2128 % For the \Env{fast} case, we define a command name:
2129 % \begin{macrocode}
2130 \global\@namedef{\bt@tempa bt@\@extra@binfo}{}%
2131 %<debug> \bt@debug{defining \bt@temp bt@\@extra@binfo}%
2132 % \end{macrocode}
2133 % In both cases, we call the original \Com{citation} command:
2134 % \begin{macrocode}
2135 \@bt@orig@citation{\bt@tempa}%
2136 }%
2137 }%
2138 }{%
2139 \def\citation#1{%
2140 \@for\bt@tempa:=#1\do{%
2141 \def\@extra@b@citeb{\bt@unit@cnt}%
2142 \bt@add@elem{\bt@tempa}{\bt@cited@list}%
2143 \@bt@orig@citation{\bt@tempa}%
2144 }%
2145 }%
2146 }
2147 % \end{macrocode}
2148 % \end{macro}
2149 %
2150 % To suppress warnings about \ErrMessage{multiply defined labels} caused by
2151 % multiple occurrences of the same label in different \Env{btUnit} environments,
2152 % we redefine \Com{bibcite} just like \Package{chapterbib.sty} does it.
2153 % In consequence, also the \Com{@citex} and \Com{nocite} commands have to be
2154 % redefined; but this is only done in case the \Env{btUnit} environment is
2155 % indeed used.
2156 % (This code is copied directly from \Package{chapterbib.sty}; we included the hooks
2157 % \citeform and \Com{citepunct} and added our own |\bt@citesurround| to
2158 % implement the \Env{breakcites} option.)
2159 % \begin{macro}{\bt@citesurround}
2160 % \changes{v1.0j}{2000/10/17}{%
2161 % Added argument (babel\slash \chCom{ifthenelse} bug)
2162 % }
2163 % \begin{macrocode}
2164 \newcommand*\bt@citesurround{}%
2165
2166 \def\bt@citesurround#1{%
2167 \ifthenelse{\not\boolean{bt@breakcites}}{%
2168 \hbox{#1}%
2169 }{%
2170 #1%
2171 }%
2172 }
2173 % \end{macrocode}
2174 % \end{macro}
2175 % \begin{macrocode}
2176 \@ifundefined{citeform}{\let\citeform\relax}{}
2177 \@ifundefined{citepunct}{\def\citepunct{,\penalty\@m\ }}{}
2178 % \end{macrocode}
2179 % Set a flag when \ThisPackage\ has been loaded after \Package{backref},
2180 % as it should be.
2181 % \begin{macrocode}
2182 \@ifpackageloaded{backref}{%
2183 \bt@after@brftrue
2184 }{%
2185 \relax
2186 }
2187 % \end{macrocode}
2188 % \begin{macro}{\bt@citex}
2189 % \begin{macrocode}
2190 \newcommand\bt@citex{}
2191 \def\bt@citex[#1]#2{% Add \@extra@b@citeb to \cite
2192 \let\@citea\@empty
2193 \@cite{%
2194 \@for\@citeb:=#2\do{%
2195 \@citea\let\@citea\citepunct
2196 \edef\@citeb{\expandafter\@firstofone\@citeb}%
2197 \if@filesw\immediate\write\@auxout{%
2198 \string\citation{\@citeb}}\fi
2199 \@ifundefined{b@\@citeb \@extra@b@citeb}{%
2200 \mbox{\reset@font\bfseries ?}%
2201 \@warning{Citation `\@citeb' on page \thepage\space
2202 undefined}\G@refundefinedtrue
2203 }{%
2204 \bt@citesurround{\citeform{\csname b@\@citeb
2205 \@extra@b@citeb\endcsname}}%
2206 }%
2207 }%
2208 }{#1}%
2209 }
2210 % \end{macrocode}
2211 % \end{macro}
2212 % \begin{macro}{\bt@nocite}
2213 % \begin{macrocode}
2214 \newcommand\bt@nocite{}
2215 \def\bt@nocite#1{%
2216 \@bsphack % Add \@extra@b@citeb to \nocite
2217 \@for\@citeb:=#1\do{%
2218 \edef\@citeb{\expandafter\@firstofone\@citeb}%
2219 \if@filesw
2220 \immediate\write\@auxout{%
2221 \string\citation{\@citeb}%
2222 }%
2223 \fi
2224 \@ifundefined{b@\@citeb\@extra@b@citeb}{%
2225 \G@refundefinedtrue
2226 \@warning{Citation `\@citeb' undefined}%
2227 }{}%
2228 }%
2229 \@esphack
2230 }
2231 % \end{macrocode}
2232 % \end{macro}
2233
2234 % \begin{macro}{\bt@setcites}
2235 % A hook to be called by btUnit to activate the redefinitions.
2236 % We don't call this in any case, since it makes \ThisPackage\
2237 % incompatible to other packages also defining \Com{@citex}.
2238 % \begin{macrocode}
2239 \newcommand*\bt@setcites{%
2240 \let\@citex\bt@citex
2241 \let\nocite\bt@nocite
2242 }
2243 % \end{macrocode}
2244 % \end{macro}
2245
2246 % \begin{macro}{\change@bibcite}
2247 % Change the \Com{bibcite} command for use with \Env{btUnit}s.
2248 % \begin{macrocode}
2249 \newcommand\change@bibcite{%
2250 \let\change@bibcite\relax
2251 \def\bibcite##1##2{%
2252 \global\@namedef{b@##1\@extra@binfo}{##2}%
2253 }%
2254 }
2255 % \end{macrocode}
2256 % \end{macro}
2257 % \begin{macro}{\the@ipfilectr}
2258 % \begin{macro}{\@extra@b@citeb}
2259 % \begin{macro}{\@extra@binfo}
2260 % Just as in \Package{chapterbib.sty}.
2261 % \begin{macrocode}
2262 \gdef\the@ipfilectr{}
2263 \def\@extra@b@citeb{\the@ipfilectr}
2264 \gdef\@extra@binfo{} % in case .aux files are left from old run.
2265 % \end{macrocode}
2266 % \end{macro}
2267 % \end{macro}
2268 % \end{macro}
2269
2270 % Commands to store the original meaning of the \Com{bibitem} commands
2271 % and of the \Com{begin} and \Com{end} code of \Env{thebibliography}.
2272 % If natbib isn't loaded, \Com{harvarditem} commands should be treated
2273 % as errors. We set a flag and give only one error message (via \Com{bt@bibtex@warning}):
2274 % \begin{macro}{\bt@saveitem}
2275 % \begin{macro}{\bt@savebib}
2276 % \begin{macro}{\bt@endsavebib}
2277 % \begin{macrocode}
2278 \newcommand\bt@saveitem{}
2279 \newcommand*\bt@savebib{}
2280 \newcommand*\bt@endsavebib{}
2281 \newif\ifbt@harvard@errs
2282 % \end{macrocode}
2283 % \end{macro}
2284 % \end{macro}
2285 % \end{macro}
2286
2287 % \begin{macro}{\AtBeginDocument}
2288 % \begin{macrocode}
2289 \AtBeginDocument{%
2290 \@ifclassloaded{scrbook}{%
2291 \global\bt@koma@classtrue
2292 }{%
2293 \@ifclassloaded{scrartcl}{%
2294 \global\bt@koma@classtrue
2295 }{%
2296 \@ifclassloaded{scrreprt}{%
2297 \global\bt@koma@classtrue
2298 }{%
2299 \relax
2300 }%
2301 }%
2302 }%
2303 \global\let\bt@savebib\thebibliography
2304 \global\let\bt@endsavebib\endthebibliography
2305 \let\bt@saveitem\bibitem
2306 \@ifpackageloaded{natbib}{%
2307 \global\bt@natbibtrue
2308 }{%
2309 \def\harvarditem{\global\bt@harvard@errstrue}%
2310 \let\harvardand\relax
2311 \let\harvardyearleft\relax
2312 \let\harvardyearright\relax
2313 }%
2314 % \end{macrocode}
2315 % Make sure the loading order of \ThisPackage\ and \Package{backref} is OK:
2316 % \begin{macrocode}
2317 \@ifpackageloaded{backref}{%
2318 \ifthenelse{\not\boolean{bt@after@brf}}{%
2319 \PackageError{%
2320 bibtopic%
2321 }{%
2322 Load bibtopic after hyperref when using the `backref'
2323 option\MessageBreak of hyperref%
2324 }{%
2325 Please see the section about `Compatibility with other^^J%
2326 packages' in bibtopic.dvi for details.
2327 }%
2328 }{}%
2329 \global\bt@brftrue
2330 }{%
2331 \relax
2332 }%
2333 }
2334 % \end{macrocode}
2335 % \end{macro}
2336
2337 % \begin{macro}{\AtEndDocument}
2338 % Various book-keeping stuff.
2339 % \begin{macrocode}
2340 \AtEndDocument{%
2341 % \end{macrocode}
2342 % The value of \Com{bt@helpctr} (total number of \Com{bibitems} in
2343 % all bibliographies) is written to the \File{.aux} file; it will
2344 % be used to compute correct indentation of bibliography items
2345 % in the next run:
2346 % \begin{macrocode}
2347 \immediate\write\@auxout{%
2348 \string\csname\space bt@set@cnt\string\endcsname{\bt@helpctr}}%
2349 %<*debug>
2350 \bt@debug{restoring meaning of \string\citation :
2351 \meaning\@bt@orig@citation}%
2352 %</debug>
2353 \def\citation#1{\@bt@orig@citation{#1}}%
2354 % \end{macrocode}
2355 % \Com{bt@addto@keyval@list} should do nothing when the \File{.aux} file is
2356 % now read for the second time:
2357 % \begin{macrocode}
2358 \let\bt@kv@add\@gobbletwo
2359 % \end{macrocode}
2360 % Warn about changed \File{.bbl} files etc.:
2361 % \begin{macrocode}
2362 \bt@files@warnings
2363 % \end{macrocode}
2364 % Warn in case the numbering (i.\,e. also the widths of
2365 % the \Com{biblabel}s) has changed:
2366 % \begin{macrocode}
2367 \ifnum\bt@helpctr=\bt@totalctr\else
2368 \PackageWarningNoLine{%
2369 bibtopic%
2370 }{%
2371 Rerun to get indentation of bibitems right%
2372 }%
2373 \fi
2374 %<debug> \bt@debug{total number of items: \bt@helpctr}%
2375 }
2376 % \end{macrocode}
2377 % \end{macro}
2378 %
2379 % ^^A --------------------------------------------------
2380 % \subsubsection{List handling stuff}
2381 % ^^A --------------------------------------------------
2382 %
2383 % Most of the following commands have been adopted from the \TeX book, p.\,378f.
2384 % They implement macro-delimited lists (the delimiter being \Com{@elt}) which
2385 % are more efficient than, say, comma-delimited lists: To check whether a given
2386 % element is contained in a list, you would have to use iterated macro calls
2387 % in the latter case, whereas in the former case, the \Com{@elt} macro might
2388 % be defined to perform the check for its argument, and then
2389 % the entire list can be executed.
2390 %
2391 % \begin{macro}{\bt@append@list}
2392 % Append |#1| to the end of list |#2|. The change is made globally.
2393 % \begin{macrocode}
2394 \newcommand*\bt@savelist{}
2395 \newcommand*\bt@append@list[2]{%
2396 %<debug> \bt@debug{appending #1 to #2}%
2397 \let\bt@savelist#2%
2398 %<*debug>
2399 \bt@debug{list is: #2}%
2400 \bt@debug{bt@savelist is: \bt@savelist}%
2401 %</debug>
2402 \protected@xdef#2{\bt@savelist\@elt{#1}}%
2403 %<debug> \bt@debug{list after append: #2}%
2404 }
2405 % \end{macrocode}
2406 % \end{macro}
2407 % \begin{macro}{\bt@add@elem}
2408 % Add |#1| to list |#2|, but only if it's not yet contained in it.
2409 % \begin{macrocode}
2410 \newcommand*\bt@add@elem[2]{%
2411 \bt@if@elem{#1}{#2}{%
2412 \relax
2413 }{%
2414 \bt@append@list{#1}{#2}%
2415 }%
2416 }
2417 % \end{macrocode}
2418 % \end{macro}
2419 % \begin{macro}{\bt@testelem}
2420 % Test if |#1| is contained in list |#2|.
2421 % \begin{macrocode}
2422 \newcommand\bt@test@cmd{}
2423 \newcommand*\bt@if@elem[2]{%
2424 \let\bt@test@cmd\@secondoftwo
2425 % \end{macrocode}
2426 % Assign |#1| to scratch macro \Com{bt@tempa} (for the \Com{ifx} test).
2427 % ^^A
2428 % ^^A Bug alert: The group was used to keep the changes to \Com{@elt} (used by \LaTeX) and
2429 % ^^A \Com{bt@tempa} local. However this results in problems with the save stack, so I
2430 % ^^A replaced bt@tempa by bt@tempc and used the \let method instead.
2431 % ^^A
2432 % \begin{macrocode}
2433 \let\bt@elt\@elt
2434 % \begingroup
2435 \protected@edef\bt@tempc{#1}%
2436 \def\@elt##1{%
2437 \protected@edef\bt@tempb{##1}%
2438 \ifx\bt@tempc\bt@tempb
2439 \let\bt@test@cmd\@firstoftwo
2440 \fi
2441 }%
2442 % \end{macrocode}
2443 % Now execute the list:
2444 % \begin{macrocode}
2445 #2%
2446 \let\@elt\bt@elt
2447 % \endgroup
2448 \bt@test@cmd
2449 }
2450 % \end{macrocode}
2451 % \end{macro}
2452 % \begin{macro}{\bt@mk@warning@list}
2453 % This will format the list |#1| so that it can be printed nicely in warnings,
2454 % with each file on a separate line. The result is saved in the token
2455 % register \Com{@temptokena} (for immediate use).
2456 % \begin{macrocode}
2457 \newcommand\bt@elt{}
2458 \newcommand*\bt@mk@warning@list[1]{%
2459 \@temptokena={}%
2460 \let\bt@elt\@elt
2461 \def\@elt##1{%
2462 \@temptokena=\expandafter{\the\@temptokena ##1\MessageBreak}%
2463 }%
2464 #1%
2465 \let\@elt\bt@elt
2466 }
2467 % \end{macrocode}
2468 % \end{macro}
2469
2470 % \begin{macro}{\bibliographystyle}
2471 % \begin{macro}{\@orig@bibliographystyle}
2472 % Redefine \Com{bibliographystyle} to set the global bibliography style
2473 % (saved in the command name \Com{bt@globalstyle}), to be
2474 % used by the \Env{btSect} environment. Save original meaning in
2475 % \Com{@orig@bibliographystyle}.
2476 % \begin{macrocode}
2477 \newcommand*\@orig@bibliographystyle{}
2478 \let\@orig@bibliographystyle\bibliographystyle
2479 \def\bibliographystyle#1{%
2480 \gdef\bt@globalstyle{#1}%
2481 \bt@info{Default bibliographystyle is `#1'}%
2482 \@orig@bibliographystyle{#1}%
2483 }
2484 % \end{macrocode}
2485 % \end{macro}
2486 % \end{macro}
2487 %
2488 % \begin{macro}{\bibliography}
2489 % The \Com{bibliography} command isn't used by \ThisPackage, but it
2490 % was used in the older `\Package{bibtopics}'. This definition just
2491 % writes an info message to the \File{.log} file.
2492 % \begin{macrocode}
2493 \def\bibliography{%
2494 \PackageWarning{%
2495 bibtopic%
2496 }{%
2497 Ignoring `\string\bibliography' command\MessageBreak
2498 (not compatible with bibtopic.sty)%
2499 }%
2500 \@gobble
2501 }
2502 % \end{macrocode}
2503 % \end{macro}
2504
2505 % \begin{macro}{\@bt@write@auxfile}
2506 % Create the additional \File{.aux} files to be read by \BibTeX:
2507 % |#1| is the argument to \Com{bibstyle},
2508 % |#2| is the argument to \Com{citation}, and
2509 % |#3| is the argument to \Com{bibdata}.
2510 % \begin{macrocode}
2511 \newcommand*\@bt@write@auxfile[3]{%
2512 % \end{macrocode}
2513 % So that we can warn the user if an \File{.aux} file has changed,
2514 % we make a backup of it here.
2515 % \begin{macrocode}
2516 \bt@can@overwrite{btaux.aux}%
2517 \bt@copy@verbatim{\thebtauxfile.aux}{btaux.aux}% +code:bt@make@backup;
2518 \immediate\closeout\bt@outfile
2519 % \end{macrocode}
2520 % Write new info to \File{.aux} file. If \Package{natbib} is loaded, we add a comment line
2521 % so that the files are different when switching to/from natbib:
2522 % \begin{macrocode}
2523 \immediate\openout\bt@outfile\thebtauxfile.aux
2524 \ifthenelse{\boolean{bt@natbib}}{%
2525 \immediate\write\bt@outfile{%
2526 \@percentchar\@percentchar\space
2527 Info from `bibtopic.sty': natbib loaded.^^J%
2528 \string\bibstyle{#1}^^J%
2529 \string\citation{#2}^^J%
2530 \string\bibdata{#3}%
2531 }%
2532 }{%
2533 \immediate\write\bt@outfile{%
2534 \string\bibstyle{#1}^^J%
2535 \string\citation{#2}^^J%
2536 \string\bibdata{#3}%
2537 }%
2538 }%
2539 \immediate\closeout\bt@outfile
2540 % \end{macrocode}
2541 % Now check if new .aux file and btaux.aux differ, and if so, give a warning,
2542 % but only if this file hadn't been warned about before (isn't in \Com{bt@warn@files}).
2543 % \begin{macrocode}
2544 \bt@if@files@differ{\thebtauxfile.aux}{btaux.aux}{%
2545 \bt@if@elem{\thebtauxfile}{\bt@warn@files}{%
2546 \relax
2547 }{%
2548 \ifthenelse{\boolean{bt@normalwarnings}}{%
2549 \PackageWarningNoLine{%
2550 bibtopic%
2551 }{%
2552 \thebtauxfile.bbl may be outdated%
2553 }%
2554 }{%
2555 \bt@appendtofile{\thebtauxfile.bbl}{%
2556 \string\csname\space
2557 bt@warn@outdated\string\endcsname{\thebtauxfile}%
2558 }%
2559 }%
2560 }%
2561 }{}% they don't differ
2562 }
2563
2564 % \end{macrocode}
2565 % \end{macro}
2566 % \begin{macro}{\bt@appendtofile}
2567 % Append |#2| to file |#1|. This is more complicated than one would
2568 % like it to be: We need to copy the file to a tmp file (\File{btbbl.aux})
2569 % and then back to the file, but this time \emph{without} closing
2570 % the filehandle, so that subsequent \Com{write}s to the file will
2571 % append to the file (rather than overwrite the contents).
2572 % (\Com{bt@closeout} closes the handle \Com{bt@outfile}, which is
2573 % always the file currently written to).
2574 % \begin{macrocode}
2575 \newcommand*\bt@appendtofile[2]{%
2576 \bt@can@overwrite{btbbl.aux}%
2577 \bt@copy@verbatim{#1}{btbbl.aux}%
2578 \immediate\closeout\bt@outfile
2579 \bt@copy@verbatim{btbbl.aux}{#1}
2580 \immediate\write\bt@outfile{\expandafter\string #2}%
2581 \immediate\closeout\bt@outfile
2582 }
2583 % \end{macrocode}
2584 % \end{macro}
2585
2586 %
2587 % The following two commands are written to the \File{.aux} file by the
2588 % \Env{btUnit} environment to handle different citation lists correctly.
2589 %
2590 % \begin{macro}{\bt@save@list}
2591 % Save \Com{bt@cited@list} by writing it to \Com{bt@sect}|#1|, where |#1| is
2592 % the current number of the \Env{btUnit} (\Com{bt@unit@cnt}).
2593 % \begin{macrocode}
2594 \newcommand*\bt@save@list[1]{%
2595 \expandafter\protected@xdef\csname bt@sect%
2596 #1\endcsname{\bt@cited@list}%
2597 %<*debug>
2598 \bt@debug{saving list #1\space is:
2599 \csname bt@sect#1\endcsname}%
2600 %</debug>
2601 }
2602 % \end{macrocode}
2603 % \end{macro}
2604 %
2605 % ^^A --------------------------------------------------
2606 % \subsubsection[\texttt{thebibliography}; parsing the \texttt{bibitem} commands]{Redefinition of
2607 % \Env{thebibliography}\\ and parsing the \Com{bibitem} commands}
2608 % ^^A --------------------------------------------------
2609 %
2610 % We'd like to be able to print only selected \Com{bibitem}s (e.\,g., those cited, or
2611 % those not cited). To select these, we make the \Com{bibitem} command fake an environment
2612 % that contains the entire item, so that it's easy to ignore its contents entirely.
2613 % That is, a \Env{thebibliography} environment like the following:
2614 % \begin{verbatim}
2615 % \begin{thebibliography}{10}
2616 % \bibitem[a] foo
2617 % \bibitem[b] bar
2618 % \bibitem[c] roo
2619 % \end{thebibliography}
2620 % \end{verbatim}
2621 % shall expand to:
2622 % \begin{verbatim}
2623 % \begin{thebibliography}{10}
2624 % \begin{myitem}[]
2625 % \end{myitem}
2626 % \begin{myitem}[a]
2627 % foo
2628 % \end{myitem}
2629 % \begin{myitem}[b]
2630 % bar
2631 % \end{myitem}
2632 % \begin{myitem}[c]
2633 % roo
2634 % \end{myitem}
2635 % \begin{myitem}[]
2636 % \end{myitem}
2637 % \end{thebibliography}
2638 % \end{verbatim}
2639 % ^^A
2640 % Note the empty \Env{myitem} environments after
2641 % \BTbegEnv{thebibliography} and before
2642 % \BTendEnv{thebibliography}, respectively: These are needed since
2643 % \Com{bibitem}\oarg{arg} is defined as
2644 % \BTendEnv{myitem}\BTbegEnv{myitem}\oarg{arg}.^^A
2645 % \footnote{Yes, this \emph{is} strange, but it seems to work -- contrary to
2646 % the other schemes I tried before (looking for certain characters
2647 % in the input, reading over stuff etc.) If you have a better idea,
2648 % please \emph{do} tell me about it!}
2649 % The missing \BTbegEnv{myitem} will be inserted by the
2650 % redefined \BTbegEnv{thebibliography} just after
2651 % the usual \Com{begin} code, and the missing \BTendEnv{myitem}
2652 % will be inserted by \BTendEnv{thebibliography}. (This is actually the
2653 % reason why we need to redefine \Env{thebibliography}).
2654 %
2655 % \begin{macro}{\btBegThbCmd}
2656 % A hook for inserting commands between the \BTbegEnv{thebibliography}
2657 % command and the first \Com{bibitem}. Currently unused.
2658 % \begin{macrocode}
2659 \newcommand\btBegThbCmd{}
2660 % \end{macrocode}
2661 % \end{macro}
2662 % \begin{macro}{\bt@beg@thb@hook}
2663 % We call the \Env{bt@item} environment here (and anywhere else)
2664 % in plain-\TeX\ fashion so that its contents are not inside a group.
2665 % This is important in case there are definitions after
2666 % \BTbegEnv{thebibliography}, which otherwise wouldn't work.
2667 % It also should reduce the general overhead.
2668 % \begin{macrocode}
2669 \newcommand*\bt@beg@thb@hook{%
2670 \btBegThbCmd
2671 \global\bt@found@itemfalse
2672 \bt@item{}%
2673 }%
2674 % \end{macrocode}
2675 % \end{macro}
2676 % \begin{macro}{\bt@end@thb@hook}
2677 % \changes{v1.0i}{2000/10/09}{%
2678 % \Package{jurabib} compatibility: Replaced \chCom{theenumiv} by
2679 % \chCom{@arabic}\chCom{c@enumiv} to fix a bug with \Package{jurabib}'s
2680 % definition of \chEnv{thebibliography}: it doesn't redefine
2681 % \chCom{theenumiv}, so \chCom{theenumiv} is still defined as
2682 % \chCom{@Alph}\chCom{c@enumiv}, expanding to `' for 0 and causing
2683 % an error later
2684 % }
2685 % \begin{macrocode}
2686 \newcommand\bt@save@cnt{0}
2687 \newcommand*\bt@end@thb@hook{%
2688 \endbt@item
2689 \ifthenelse{\boolean{bt@natbib}}{%
2690 \protected@xdef\bt@save@cnt{\theNAT@ctr}%
2691 }{%
2692 \protected@xdef\bt@save@cnt{\@arabic\c@enumiv}%
2693 }%
2694 \bt@bibitemcheck
2695 }%
2696 % \end{macrocode}
2697 % \end{macro}
2698 % \begin{macro}{\bt@change@bibitem}
2699 % This command is called from the \Com{btPrint...}
2700 % commands; it changes the \Com{harvarditem} and \Com{bibitem} commands to
2701 % call our `fake' environments that do the optional printing of the
2702 % bibitems.
2703 % \begin{macrocode}
2704 \newcommand*\bt@change@bibitem{%
2705 \expandafter\ifx\btBegThbCmd\empty\else
2706 \bt@info{\string\btBegThbCmd nonempty: \meaning\btBegThbCmd}%
2707 \fi
2708 % \end{macrocode}
2709 % \changes{v0.1}{1999/09/20}{%
2710 % Added reset to switch \chCom{@bt@found@item@}
2711 % }
2712 % The switch \Com{@bt@found@item@} is set to false again for the start of
2713 % a new bibliography.
2714 % \begin{macrocode}
2715 \ifthenelse{\boolean{bt@natbib}}{%
2716 \def\harvarditem{\endbt@item\bt@harvitem}%
2717 }{}%
2718 \def\bibitem{\endbt@item\bt@item}%
2719 }
2720 % \end{macrocode}
2721 % \end{macro}
2722 %
2723 % \begin{macro}{\bt@adjust@label}
2724 % Set up the space needed for the bibliography labels.^^A
2725 % \footnote{^^A
2726 % The required space can't be simply calculated from the first argument
2727 % of \Env{thebibliography}: with \File{plain.bst} this argument (if numerical)
2728 % just contains a symbolic representation $x$ for the width of the numerical labels,
2729 % computed as follows (see the function \Env{longest.label.pass} in \File{plain.bst}):
2730 % $x = 10^n$, where $n = {}${\itshape stringlen} ({\itshape
2731 % number of the last item})${} - 1$.
2732 % (So, for example, $x = 1$ for a bibliography containing less than 10 items,
2733 % and $x = 10$ for a bibliography containing less than 100 labels. Annoying, isn't it?)}
2734 % ^^A
2735 % The maximal number of \Com{bibitems} is contained in the counter
2736 % \Com{bt@totalctr} (read from the \File{.aux} file from the previous
2737 % run); we use it to set the value for the indentation of \emph{all} item labels.
2738 % ^^A
2739 % \begin{macrocode}
2740 \newcommand*\bt@adjust@label[1]{% +code:bt@adjust@label;
2741 \bt@isnum{#1}{%
2742 \def\bt@label{\bt@totalctr}%
2743 }{%
2744 \def\bt@label{#1}%
2745 }%
2746 }
2747 % \end{macrocode}
2748 % \end{macro}
2749 % \begin{macro}{\bt@change@thb}
2750 % The following command for changing \Env{thebibliography}
2751 % was adopted from the \Com{sectionbib} command
2752 % in \Package{chapterbib.sty} (D. Arseneau).
2753 % Its main purposes are:
2754 % ^^A
2755 % \begin{itemize}
2756 % \item
2757 % (optionally) remove the headings from \Env{thebibliography}
2758 % (user will set his own with the ordinary sectioning commands),
2759 % \item
2760 % (optionally) remove the reset of the bibitem counter for numerical citation styles,
2761 % \item
2762 % call the \Com{bt@item} command immediately after opening \Com{thebibliography},
2763 % and the \Com{endbt@item} command before closing \Com{thebibliography}.
2764 % This might be requested only conditionally (wouldn't need it for \Com{btPrintAll}
2765 % -- currenlty it's just always used), so we use the hooks
2766 % \Com{bt@beg@thb@hook} and \Com{bt@end@thb@hook} that are set up
2767 % by calling \Com{bt@change@bibitem}.
2768 % \end{itemize}
2769 % We check what kind of \Env{thebibliography} environment we're dealing with, and
2770 % call the appropriate command to do the changes: \Com{bt@mydochangechange@nat@thb},
2771 % \Com{bt@change@default@thb} or \Com{bt@change@KOMA@thb}.
2772 % ^^A
2773 % \begin{macrocode}
2774 \newcommand*\bt@change@thb{%
2775 \long\def\bt@tempa##1##2\endthebibliography{%
2776 \def\bt@tempc{##1}%
2777 }%
2778 \expandafter\bt@tempa\thebibliography{}\endthebibliography
2779 % \end{macrocode}
2780 % With the \Package{backref} package, \Com{thebibliography} is overloaded
2781 % to start with \Com{@starttoc}, and we have to look at
2782 % the redefined command instead. The original command is saved by
2783 % \Package{backref} either as \Com{oldbibl}
2784 % (for versions $\leq$ 1.16 from 1999/04/12) or as \Com{BRorg@thebibliography}
2785 % (for version 1.19 from 2000/01/19).
2786 % \begin{macrocode}
2787 \ifthenelse{\boolean{bt@brf}}{%
2788 \@ifundefined{BRorg@thebibliography}{%
2789 \PackageInfo{bibtopic}{assuming backref.sty <= v1.16}%
2790 \let\bt@brf@bbl@cmd\oldbibl
2791 }{%
2792 \PackageInfo{bibtopic}{assuming backref.sty >= v1.19}%
2793 \let\bt@brf@bbl@cmd\BRorg@thebibliography
2794 }%
2795 \def\bt@tempb{\@starttoc}%
2796 \ifx\bt@tempb\bt@tempc
2797 \expandafter\bt@tempa\bt@brf@bbl@cmd{}\endthebibliography
2798 \fi
2799 }{}%
2800 % \end{macrocode}
2801 % If a {\scshape KOMA}-class is loaded, the first command in
2802 % \Env{thebibliography} is \Com{bib@heading}; for \Package{natbib} v6.x
2803 % it's \Com{bibfont}, for \Package{natbib} v7 it's \Com{bibsection}.
2804 % KOMA versions ${}\geq 2.9$ are dealt with below.
2805 % \begin{macrocode}
2806 \def\bt@tempa{\bibfont}%
2807 \ifx\bt@tempa\bt@tempc %
2808 %<debug> \bt@debug{assuming natbib v6.x-style thb env}%
2809 \bt@change@nat@thb
2810 \else
2811 \def\bt@tempa{\bibsection}%
2812 \ifx\bt@tempa\bt@tempc
2813 %<debug> \bt@debug{assuming natbib v7-style thb env}%
2814 \bt@change@nat@thb
2815 \else
2816 \def\bt@tempa{\bib@heading}%
2817 \ifx\bt@tempa\bt@tempc
2818 %<debug> \bt@debug{assuming older KOMA-style thb env}%
2819 \bt@change@KOMA@thb
2820 % \end{macrocode}
2821 % Check if the definition from the standard classes is used. This begins
2822 % with either \Com{section} (for \Env{article}) or \Com{chapter} (for \Env{report}
2823 % or \Env{book}).
2824 % \begin{macrocode}
2825 \else
2826 \def\bt@tempa{\chapter}%
2827 \ifx\bt@tempa\bt@tempc
2828 %<debug> \bt@debug{assuming book thb env}%
2829 \bt@change@standard@thb
2830 \else
2831 \def\bt@tempa{\section}%
2832 \ifx\bt@tempa\bt@tempc
2833 %<debug> \bt@debug{assuming article thb env}%
2834 \bt@change@standard@thb
2835 \else
2836 % \end{macrocode}
2837 % With newer KOMA versions, \Com{bib@heading} is not at the beginning of
2838 % \Com{thebibliography}; but for these we can assume that \Com{bib@heading}
2839 % will be available, so \Com{bt@change@KOMA@thb} should work.
2840 % \begin{macrocode}
2841 \ifbt@koma@class
2842 %<debug> \bt@debug{assuming newer KOMA-style thb env}%
2843 \bt@change@KOMA@thb
2844 \else
2845 % \end{macrocode}
2846 % Nothing appropriate at all; either use the fallback definition if
2847 % \Env{defaultbib} option has been specified, or complain:
2848 % \begin{macrocode}
2849 \ifthenelse{\boolean{bt@fallback@thb}}{%
2850 \PackageWarning{%
2851 bibtopic%
2852 }{%
2853 `defaultbib' specified; using
2854 built-in\MessageBreak
2855 `thebibliography' environment%
2856 }%
2857 \let\thebibliography\bt@dflt@bthb
2858 \let\endthebibliography\bt@dflt@ethb
2859 }{%
2860 \PackageError{%
2861 bibtopic%
2862 }{%
2863 Found unknown `thebibliography' environment%
2864 }{%
2865 You should either use a package providing
2866 a known bibliography^^J%
2867 environment (such as natbib), or use the
2868 `defaultbib' package^^J%
2869 option as a workaround; please see the
2870 section about `Warnings^^J%
2871 and error messages' in `bibtopic.dvi' for
2872 details.
2873 }%
2874 }%
2875 \fi
2876 \fi
2877 \fi
2878 \fi
2879 \fi
2880 \fi
2881 }
2882 % \end{macrocode}
2883 % \end{macro}
2884
2885 % \begin{macro}{\bt@dflt@bthb}
2886 % When the \Env{defaultbib} option is specified, this definition is used
2887 % instead of an incompatible definition of \Env{thebibliography}.
2888 % It is similar to the definition found in the \textsc{KOMA} classes.
2889 % \begin{macrocode}
2890 \providecommand\@openbib@code{}
2891 \newcommand\bt@dflt@bthb[1]{%
2892 \bt@adjust@label{#1}%
2893 \ifthenelse{\boolean{bt@printheadings}}{%
2894 \@ifundefined{chapter}{%
2895 \@ifundefined{section}{%
2896 % \end{macrocode}
2897 % Use the \LaTeX2e kernel command directly to print a section heading -- this works only
2898 % because the \Env{section}-related stuff (\Com{thesection}, \Com{l@section}, which
2899 % needn't be defined for any documentclass) isn't called for the |*|-form.
2900 % \begin{macrocode}
2901 \@startsection{section}{1}{\z@}%
2902 {-3.5ex \@plus -1ex \@minus -.2ex}%
2903 {2.3ex \@plus.2ex}%
2904 {\normalfont\Large\bfseries}*{\refname}%
2905 }{%
2906 \section*{\refname\@mkboth{\refname}{\refname}}%
2907 }%
2908 }{%
2909 \chapter*{\bibname\@mkboth{\bibname}{\bibname}}%
2910 }%
2911 }{}%
2912 \list{\@biblabel{\@arabic\c@enumiv}}{%
2913 \settowidth\labelwidth{\@biblabel{#1}}%
2914 \leftmargin\labelwidth
2915 \advance\leftmargin\labelsep
2916 \@openbib@code
2917 \ifthenelse{\boolean{bt@sectctr@reset}}{%
2918 \usecounter{enumiv}%
2919 }{%
2920 \@nmbrlisttrue
2921 \def\@listctr{enumiv}%
2922 }%
2923 \let\p@enumiv\@empty
2924 \renewcommand*\theenumiv{\@arabic\c@enumiv}%
2925 }%
2926 \sloppy\clubpenalty4000\widowpenalty4000%
2927 \sfcode`\.=\@m
2928 \bt@beg@thb@hook
2929 }%
2930 % \end{macrocode}
2931 % \end{macro}
2932
2933 % \begin{macro}{\bt@dflt@ethb}
2934 % Fallback code for the end of the environment:
2935 % \begin{macrocode}
2936 \newcommand\bt@dflt@ethb{%
2937 \bt@end@thb@hook
2938 \def\@noitemerr{%
2939 \@latex@warning{Empty `thebibliography' environment}%
2940 }%
2941 \endlist
2942 }%
2943 % \end{macrocode}
2944 % \end{macro}
2945
2946 % \begin{macro}{\bt@change@nat@thb}
2947 % Change the definition of the \Package{natbib}
2948 % \Env{thebibliography} definition. We call our adjusting macro for
2949 % the label width, and optionally disable \Com{setcounter} to get continuous
2950 % numbering and the \Package{natbib} hook \Com{bibsection}.
2951 % \begin{macrocode}
2952 \newcommand\bt@change@nat@thb{%
2953 %<debug> \bt@debug{Changing natbib-style thebibliography}%
2954 \def\thebibliography##1{%
2955 \bt@adjust@label{##1}%
2956 \ifthenelse{\not\boolean{bt@printheadings}}{%
2957 \let\bibsection\relax
2958 }{}%
2959 % \end{macrocode}
2960 % Call the original \BTbegEnv{thebibliography} command:
2961 % \begin{macrocode}
2962 \bt@savebib{\bt@label}% +code:bt@thb@headings;
2963 \ifthenelse{\not\boolean{bt@sectctr@reset}}{%
2964 \setcounter{NAT@ctr}{\bt@save@cnt}%
2965 }{}%
2966 \bt@beg@thb@hook
2967 }%
2968 % \end{macrocode}
2969 % Similarly for the original \BTendEnv{thebibliography} command:
2970 % \Com{bt@end@thb@hook} calls \Com{endbt@item}. We \emph{don't} call
2971 % \Com{bt@endsavebib} here, but overwrite the \Package{natbib}
2972 % \Com{endthebibliography} definition
2973 % explicitly: it adds a \Com{vskip}-\Com{lastskip} after the \Com{endlist}, which
2974 % produces differently (horribly) looking results if natbib is loaded before
2975 % \ThisPackage; I guess this would be buggy behaviour.
2976 % \begin{macrocode}
2977 \def\endthebibliography{%
2978 \bt@end@thb@hook
2979 % \bt@endsavebib %% not; define it explicitly instead:
2980 \def\@noitemerr{%
2981 \PackageWarning{%
2982 bibtopic%
2983 }{%
2984 Empty `thebibliography' environment%
2985 }%
2986 }%
2987 \endlist % \vskip-\lastskip omitted here
2988 }%
2989 }
2990 % \end{macrocode}
2991 % \end{macro}
2992
2993 % \begin{macro}{\bt@change@standard@thb}
2994 % The standard classes' \Env{thebibliography}. Most of the
2995 % commands are similar to the \Package{natbib} case before, with the
2996 % exception that we disable \Com{usecounter} instead of \Com{setcounter}
2997 % unless the option \Env{sectcntreset} has been used.
2998 % \begin{macrocode}
2999 \newcommand*\bt@change@standard@thb{%
3000 \def\thebibliography##1{%
3001 \bt@adjust@label{##1}%
3002 \ifthenelse{\not\boolean{bt@printheadings}}{%
3003 % \end{macrocode}
3004 % These \Com{let}s are local to the current definition:
3005 % \begin{macrocode}
3006 \let\chapter\@gobbletwo
3007 \let\section\@gobbletwo
3008 }{}%
3009 \bt@savebib{\bt@label}%
3010 \ifthenelse{\not\boolean{bt@sectctr@reset}}{%
3011 \setcounter{enumiv}{\bt@save@cnt}%
3012 }{}%
3013 \bt@beg@thb@hook
3014 }%
3015 \def\endthebibliography{%
3016 \bt@end@thb@hook
3017 \bt@endsavebib
3018 }%
3019 }
3020 % \end{macrocode}
3021 % \end{macro}
3022 % \begin{macro}{\bt@change@KOMA@thb}
3023 % To remove the headings from a \textsc{KOMA}
3024 % \Env{thebibliography}, we disable \textsc{KOMA}'s hook
3025 % \Com{bib@heading}. Then we call the default procedure
3026 % \Com{bt@change@standard@thb}. (TODO: Should KOMA's \Com{bibpreamble}
3027 % be preserved? The usual way with \Package{bibtopic} is to specify headers
3028 % and additional text in-line. The only problem is that the text is
3029 % ignored, and users may not realize that.)
3030 % \begin{macrocode}
3031 \newcommand*\bt@change@KOMA@thb{%
3032 \ifthenelse{\not\boolean{bt@printheadings}}{%
3033 \let\bib@heading\relax
3034 }{}%
3035 \bt@change@standard@thb
3036 }
3037 % \end{macrocode}
3038 % \end{macro}
3039
3040 % \begin{macro}{\bt@harvitem}
3041 % Replacement for \Com{harvarditem} (set up by \Com{bt@change@bibitem}).
3042 % \begin{macrocode}
3043 \newcommand\bt@harvitem{%
3044 \@ifnextchar[{\bt@@harvitem}{\bt@@harvitem[]}%] brace matching
3045 }
3046 % \end{macrocode}
3047 % \end{macro}
3048
3049 % \begin{macro}{\bt@@harvitem}
3050 % \Package{natbib} maps the arguments of \Com{harvarditem} to the optional
3051 % argument of \Com{bibitem}, inserting braces as separators.
3052 % We just do the same here. (I guess that we could also
3053 % check for the presence of the unchanged definition of \Com{harvarditem},
3054 % as for \Env{thebibliography} just before. But would it be worth it?).
3055 % \begin{macrocode}
3056 \newcommand*\bt@@harvitem[4][]{%
3057 %<debug> \bt@debug{btharvitem called with args: |#1|#2|#3|#4|}%
3058 \ifthenelse{\equal{#1}{}}{%
3059 \protected@xdef\bt@args{[#2(#3)]}%
3060 }{%
3061 \bt@warn@brackets{#2}#1[]\end%
3062 \protected@xdef\bt@args{[#1(#3)#2]}%
3063 }%
3064 \bt@call@item{#4}%
3065 }
3066 % \end{macrocode}
3067 % \end{macro}
3068 %
3069 % \begin{environment}{bt@item}
3070 % Replacement for \Com{bibitem}.
3071 % \begin{macrocode}
3072 \newenvironment{bt@item}{%
3073 \@ifnextchar[{\bt@@item}{\bt@@item[]}%] brace matching
3074 }{
3075 \relax
3076 }
3077 % \end{macrocode}
3078 % \end{environment}
3079 % \begin{macro}{\bt@@item}
3080 % Do some argument checking: if the optional argument is numerical,
3081 % it will most probably mess up our own continuous numbering,
3082 % so we ignore this number and give a warning. This behaviour
3083 % can be customized by the options \Env{overridenumbers} and \Env{dontoverridenumbers}
3084 % which set the switches \Env{@bt@override@numargs@} and \Env{@bt@warn@override@}
3085 % appropriately (see there).
3086 % At the end we call the original commands with the arguments (the
3087 % optional argument is in \Com{bt@args}).
3088 % \changes{v1.0a}{1999/07/06}{%
3089 % Replaced \chCom{edef} here and
3090 % in other places by \chCom{protected@edef}
3091 % }
3092 % \begin{macrocode}
3093 \newcommand*\bt@@item[2][]{%
3094 \ifthenelse{\equal{#2}{}}{%
3095 % \end{macrocode}
3096 % In this case, the current item is one of the `dummy' items at the
3097 % beginning or end of \Env{thebibliography}. We do nothing in this case
3098 % (don't call \Com{bt@call@item}, so that commands eventually occurring
3099 % at this place are still executed etc.).
3100 % \begin{macrocode}
3101 \def\endbt@item{\relax}%
3102 }{%
3103 \ifthenelse{\equal{#1}{}}{%
3104 \gdef\bt@args{}%
3105 }{%
3106 \bt@isnum{#1}{%
3107 \ifthenelse{\boolean{bt@override@numargs}}{%
3108 \global\bt@overridden@numargstrue
3109 \gdef\bt@args{}%
3110 }{%
3111 \bt@warn@brackets{#2}#1[]\end%
3112 \protected@xdef\bt@args{[#1]}%
3113 }%
3114 }{%
3115 \bt@warn@brackets{#2}#1[]\end%
3116 \protected@xdef\bt@args{[#1]}%
3117 }%
3118 }%
3119 \bt@call@item{#2}%
3120 }%
3121 }
3122 % \end{macrocode}
3123 % \end{macro}
3124 % \begin{macro}{\bt@warn@brackets}
3125 % Warn user if brackets inside the argument of the \Com{bt@@item} command might
3126 % confuse \Com{bt@call@item}. This might happen with keys in the \File{.bbl}
3127 % file looking like this: ``\File{key = \Obr[FOO]\Cbr}''. Such keys should be enclosed into
3128 % another pair of braces to protect them.
3129 % \begin{macrocode}
3130 \newcommand*\bt@warn@brackets{}
3131 \def\bt@warn@brackets#1#2[#3]#4\end{%
3132 \ifthenelse{\equal{#3}{}}{%
3133 \relax
3134 }{%
3135 \PackageError{%
3136 bibtopic%
3137 }{%
3138 Can't parse brackets in key `#1' properly%
3139 }{%
3140 You seem to have used brackets `[]' inside that key in^^J%
3141 `\bt@curr@[email protected]', and bibtopic could have confused these^^J%
3142 with the optional argument of the `\string\bibitem' command.^^J%
3143 To avoid this, please `hide' such brackets in an extra pair^^J%
3144 of braces, like this: `{[]}'.^^J^^J%
3145 (Don't forget to rerun BibTeX on `\thebtauxfile' afterwards.)^^J%
3146 If you proceed now, your bibliograpy may look somewhat garbled.
3147 }%
3148 }%
3149 }
3150 % \end{macrocode}
3151 % \end{macro}
3152
3153 %
3154 % \begin{macro}{\bt@boxing@hook}
3155 % \changes{v1.0d}{2000/06/17}{%
3156 % Added this hook
3157 % }
3158 % \changes{v1.0i}{2000/10/09}{%
3159 % \Package{jurabib} compatibility: Added \chCom{jbdoitem} and \chCom{jbbibargs}
3160 % to \chCom{bt@boxing@hook}
3161 % }
3162 % The following hook disables `dangerous' commands that could
3163 % cause side-effects inside a \Com{bibitem} that should be
3164 % skipped. For example, some styles insert a \Env{quotation}
3165 % environment for comments, causing a \Com{@noitemerr} in this
3166 % case. (I guess this shows that the method with the \Env{lrbox}
3167 % isn't really bullet-proof, since it only prevents typesetting,
3168 % but not exection of commands. Is there a better way to implement
3169 % this?) The hook is called inside an \Env{lrbox} environment, so
3170 % all redefinitions are local to that environment.
3171 % \begin{macrocode}
3172 \newcommand*\bt@boxing@hook{%
3173 \global\let\@noitemerr\relax
3174 % \end{macrocode}
3175 % Disable all citation commands that might occur as cross references in
3176 % entries we want to ignore.
3177 % \begin{macrocode}
3178 \def\cite{%
3179 \@ifstar{}{}% just gobble it
3180 \@ifnextchar[{% brace matching }]{
3181 \@citex
3182 }{%
3183 \@citex[]%
3184 }%
3185 }
3186 \def\@citex[##1]{%
3187 \@ifnextchar[{% brace matching }]{
3188 \bt@gobble@citex[##1]%
3189 }{%
3190 \bt@gobble@citex[##1][]%
3191 }%
3192 }%
3193 \def\bt@gobble@citex[##1][##2]##3{}%
3194 % \end{macrocode}
3195 % Most of these are from \Package{natbib.sty}.
3196 % \begin{macrocode}
3197 \let\citet\cite
3198 \let\Citet\cite
3199 \let\citep\cite
3200 \let\Citep\cite
3201 \let\citealt\cite
3202 \let\Citealt\cite
3203 \let\citealp\cite
3204 \let\Citealp\cite
3205 \let\citetext\cite
3206 \let\citeauthor\cite
3207 \let\Citeauthor\cite
3208 \let\citeauthoryear\cite
3209 \let\citeyearpar\cite
3210 \let\citetalias\cite
3211 \let\citepalias\cite
3212 % \end{macrocode}
3213 % \Package{jurabib} typesets a bibitem by calling these commands:
3214 % \begin{macrocode}
3215 \let\jbdoitem\relax
3216 \let\jbbibargs\bt@gobblethree
3217 % \end{macrocode}
3218 % To make \Env{ibidem@author} in \Package{jurabib} work:
3219 % \begin{macrocode}
3220 \let\bibnf\relax
3221 \let\bibrnf\relax
3222 \let\bibenf\relax
3223 \let\bibrenf\relax
3224 }
3225 % \end{macrocode}
3226 % \end{macro}
3227
3228 % \begin{macro}{\bt@call@item}
3229 % This command does the real `hard work': it checks if the current item had been
3230 % cited or not (using \Com{bt@testelem}) and takes the appropriate actions
3231 % according on the value of the booleans \Env{@bt@print@$\{$positive$\mid$all$\}$@}:
3232 % \begin{itemize}
3233 % \item print the item, in which case we do next to nothing (only keyval and bookkeeping
3234 % stuff);
3235 % \item don't print the item: In this case, we put the entire item into a \Env{lrbox}
3236 % that we just won't use any more; i.\,e. we throw it away. There may
3237 % be more efficient/elegant ways to do this, but `scanning over it'-schemes
3238 % would not work since the \Com{end} code of these items isn't standing
3239 % verbatim in the input (but only the next \Com{bibitem} command that will
3240 % expand to it).
3241 % \end{itemize}
3242 % Again, we differentiate a `fast' and a `slow' case
3243 % (the cases where items should be printed are just reversed).
3244 % \begin{macrocode}
3245 \newcommand*\bt@call@item{}
3246 \ifthenelse{\boolean{bt@fast}}{%
3247 \def\bt@call@item#1{%
3248 %<debug> \bt@debug{bt@call@item called with arg: |#1|}%
3249 \@ifundefined{#1bt@\@extra@b@citeb}{%
3250 \bt@print@all@or@notcited{#1}%
3251 }{%
3252 \bt@print@all@or@cited{#1}%
3253 }%
3254 }
3255 }{%
3256 % \end{macrocode}
3257 % The `slow' case. Instead of the internal table of command names,
3258 % we make the lookup in our list of cited items. Except for this
3259 % (and the fact that the positive\slash nonpositive cases are inversed)
3260 % there's not much difference to the above.
3261 % \begin{macrocode}
3262 \def\bt@call@item#1{%
3263 %<debug> \bt@debug{bt@call@item called with arg: |#1|}%
3264 \def\endbt@item{\relax}%
3265 \bt@if@elem{#1}{\csname bt@sect\bt@unit@cnt\endcsname}{%
3266 \bt@print@all@or@cited{#1}%
3267 }{%
3268 \bt@print@all@or@notcited{#1}%
3269 }%
3270 }%
3271 }
3272 % \end{macrocode}
3273 % \end{macro}
3274
3275 % \begin{macro}{\bt@print@all@or@cited}
3276 % This macro prints all items or those actually cited.
3277 % \begin{macrocode}
3278 \newcommand*\bt@print@all@or@cited[1]{%
3279 \ifthenelse{\boolean{bt@print@cited}}{%
3280 \bt@do@print@item{#1}%
3281 }{%
3282 \ifthenelse{\boolean{bt@print@all}}{%
3283 \bt@do@print@item{#1}%
3284 }{%
3285 \bt@dont@print@item
3286 }%
3287 }%
3288 }
3289 % \end{macrocode}
3290 % \end{macro}
3291 % \begin{macro}{\bt@print@all@or@notcited}
3292 % This macro prints all items or those not cited.
3293 % \begin{macrocode}
3294 \newcommand*\bt@print@all@or@notcited[1]{%
3295 \ifthenelse{\boolean{bt@print@cited}}{%
3296 %<*debug>
3297 \bt@debug{printing cited: #1}%
3298 %</debug>
3299 \bt@dont@print@item
3300 }{%
3301 \bt@do@print@item{#1}%
3302 }%
3303 }
3304 % \end{macrocode}
3305 % \end{macro}
3306 % \begin{macro}{\bt@do@print@item}
3307 % Actually prints the item.
3308 % \begin{macrocode}
3309 \newcommand*\bt@do@print@item[1]{%
3310 \global\bt@found@itemtrue
3311 \bt@stepcnt\bt@helpctr
3312 \bt@if@elem{#1}{\bt@kv@req@list}{%
3313 \bt@add@elem{#1}{\bt@sect@ref@list}% +code:bt@sect@ref@listAdd;
3314 }{}%
3315 \def\endbt@item{\relax}%
3316 \expandafter\bt@saveitem\bt@args{#1}%
3317 }
3318
3319 \newbox\bt@tempboxa
3320
3321 \newcommand*\bt@dont@print@item{%
3322 \def\endbt@item{%
3323 \end{lrbox}%
3324 }%
3325 \begin{lrbox}{\bt@tempboxa}%
3326 \bt@boxing@hook
3327 }
3328 % \end{macrocode}
3329 % \end{macro}
3330 %
3331 % \begin{macro}{\bt@copy@verbatim}
3332 % Copy |#1| to |#2|. |#2| isn't closed, so
3333 % subsequent \Com{write}s to |#2| can be used to append lines to |#2|.
3334 % \begin{macrocode}
3335 \newcommand\bt@copy@verbatim[2]{%
3336 % \PackageInfo{bibtopic}{Making backup of #1 ...}%
3337 \openin\bt@infilea=#1\relax
3338 \immediate\openout\bt@outfile=#2\relax
3339 % \end{macrocode}
3340 % Write our signature to the file:
3341 % \begin{macrocode}
3342 \immediate\write\bt@outfile{%
3343 \@percentchar%
3344 \@percentchar%
3345 \@percentchar%
3346 \space produced automatically by bibtopic.sty v1.1%
3347 }%
3348 \begingroup
3349 \let\do\@makeother \dospecials
3350 \endlinechar\m@ne
3351 \ifeof\bt@infilea
3352 \bt@info{Tried to copy #1, but couldn't find it}%
3353 \else
3354 \loop
3355 \read\bt@infilea to\bt@tempa
3356 %<debug> \bt@debug{LINE: \bt@tempa}%
3357 % same trick as with \if!...!
3358 \if\ifeof\bt@infilea 0\else 1\fi 1
3359 \immediate\write\bt@outfile{\bt@tempa}%
3360 \repeat
3361 \fi
3362 \endgroup
3363 % \end{macrocode}
3364 % Closing \Com{bt@outfile} is done optionally in the calling macro
3365 % (to make it possible to append stuff).
3366 % \begin{macrocode}
3367 \closein\bt@infilea
3368 }
3369 % \end{macrocode}
3370 % \end{macro}
3371 %
3372 % \begin{macro}{\bt@can@overwrite}
3373 % Check if we can overwrite |#1|, i.e. if it is a file produced by
3374 % \ThisPackage. This is veryfied by checking if the first line of
3375 % the file is a `signature' line of the following form:\medskip
3376 %
3377 % \noindent{\footnotesize\begin{tabular}{@{}l}
3378 % \verb|%%% produced automatically by bibtopic.sty v|^^A
3379 % $\langle$major-version$\rangle$|.|$\langle$minor-version$\rangle$
3380 % \end{tabular}}
3381 %
3382 % \begin{macrocode}
3383 \newcommand*\bt@can@overwrite[1]{%
3384 \openin\bt@infilea=#1\relax
3385 \bgroup
3386 \let\do\@makeother \dospecials
3387 \endlinechar\m@ne
3388 \ifeof\bt@infilea
3389 \bt@info{File `#1' doesn't exist}%
3390 \else
3391 \read\bt@infilea to\@tempa
3392 \ifeof\bt@infilea
3393 \bt@info{File `#1' is empty}%
3394 \else
3395 \bt@if@signatureline{\@tempa}{%
3396 \relax
3397 }{%
3398 \PackageError{bibtopic}{%
3399 file `#1' not written by bibtopic%
3400 }{%
3401 The file `#1' looks as if it hasn't been written
3402 by bibtopic;^^J%
3403 however, bibtopic would now try to overwrite this file.^^J%
3404 (See section 3 in bibtopic.dvi for more details.)^^J%
3405 If this file contains anything important, please^^J%
3406 copy its contents to a safe place now.^^J^^J%
3407 If you hit RETURN now, this file will be overwritten.^^J%
3408 }%
3409 }%
3410 \fi
3411 \fi
3412 \egroup
3413 \closein\bt@infilea
3414 }
3415 % \end{macrocode}
3416 % \end{macro}
3417
3418 % \begin{macro}{\bt@if@signatureline}
3419 % \begin{macro}{\bt@if@@signatureline}
3420 % Checks if the argument starts with a signature line of the format described
3421 % for \Com{bt@can@overwrite} above. `\verb|%|' and `\verb*| |' are \Com{catcode}d
3422 % to `other' to match the catcodes in the line just read, and
3423 % \Com{endlinechar} is unset for convenience (so that we don't need to
3424 % uncomment line endings). The version is extracted and written to
3425 % \Com{bt@version}, even if we don't use it currently.
3426 % \begin{macrocode}
3427 \newcommand\bt@version{0}
3428 \newcommand\bt@if@@signatureline{}
3429 \newcommand\bt@if@signatureline{}
3430 {
3431 % \end{macrocode}
3432 % This group is used to keep the \Com{catcode} changes local.
3433 % \begin{macrocode}
3434 \catcode`\ =12
3435 % \end{macrocode}
3436 % Note: no spaces from here on. Use \Com{endlinechar}\Com{m@ne}
3437 % so that line endings needn't be escaped (`\%' couldn't be used for that).
3438 % \begin{macrocode}
3439 \catcode`\%=12
3440 \endlinechar\m@ne
3441 \gdef\bt@if@signatureline#1{
3442 \expandafter\bt@if@@signatureline
3443 #1%%% produced automatically by bibtopic.sty v.%%%\end
3444 }
3445 \gdef\bt@if@@signatureline
3446 #1%%% produced automatically by bibtopic.sty v#2.#3%%%#4\end{
3447 \ifx\\#2\\
3448 \let\bt@tempc\@secondoftwo
3449 \else
3450 \def\bt@version{#2.#3}
3451 \let\bt@tempc\@firstoftwo
3452 \fi
3453 \bt@tempc
3454 }
3455 }
3456 % \end{macrocode}
3457 % \end{macro}
3458 % \end{macro}
3459
3460 % \begin{macro}{\bt@if@files@differ}
3461 % Execute |#3| if the files |#1| and |#2| differ,
3462 % |#4| if they don't differ.
3463 % \changes{v1.0j}{2000/10/17}{%
3464 % Replaced \chCom{@firstofone}, \chCom{@firstoftwo} at end by
3465 % additional args (babel\slash \chCom{ifthenelse} bug)
3466 % }
3467 % \begin{macrocode}
3468 \newif\ifbt@cont
3469 \newif\ifbt@files@diff
3470 \newcommand\bt@line@cnt{}
3471 \newcommand*\bt@if@files@differ[4]{% +code:bt@if@files@differ;
3472 %<debug> \bt@debug{comparing #1.aux - #1.bak ...}%
3473 \bt@files@difffalse
3474 \def\bt@line@cnt{0}%
3475 \bgroup
3476 \let\do\@makeother
3477 \dospecials
3478 \endlinechar-1
3479 \openin\bt@infilea=#1
3480 \openin\bt@infileb=#2
3481 % \end{macrocode}
3482 % Set continuation flag to \emph{true}, and enter reading loop.
3483 % \begin{macrocode}
3484 \bt@conttrue
3485 \loop
3486 % \end{macrocode}
3487 % This catches the normal termination case and also the case
3488 % where one of the files doesn't exist or is empty
3489 % (at EOF just after opening it):
3490 % \begin{macrocode}
3491 \ifeof\bt@infilea
3492 %<debug> \bt@debug{EOF #1}%
3493 \bt@contfalse
3494 \ifeof\bt@infileb
3495 %<debug> \bt@debug{EOF #2}%
3496 \else
3497 % \end{macrocode}
3498 % At EOF at file $a$, but not at EOF at file $b$: files are different.
3499 % \begin{macrocode}
3500 %<debug> \bt@debug{NOT at EOF #1.bak, but EOF #1.aux}%
3501 \global\bt@files@difftrue
3502 \fi
3503 \else
3504 \ifeof\bt@infileb
3505 % \end{macrocode}
3506 % At EOF at file $b$, but not at EOF at file $a$:
3507 % \begin{macrocode}
3508 %<debug> \bt@debug{EOF #1.bak}%
3509 \bt@contfalse
3510 \global\bt@files@difftrue
3511 \fi
3512 \fi
3513 % \end{macrocode}
3514 % Not at EOF; read the lines to scratch macros \Com{bt@tempa} and \Com{bt@tempb}:
3515 % \begin{macrocode}
3516 \ifbt@cont
3517 %<debug> \bt@debug{NOT at EOF of both.}%
3518 \read\bt@infilea to\bt@tempa
3519 \read\bt@infileb to\bt@tempb
3520 % \end{macrocode}
3521 % first line in file |#2| might be signature line; skip over it (file |#1| doesn't have
3522 % such a line):
3523 % \begin{macrocode}
3524 \bt@stepcnt{\bt@line@cnt}%
3525 \ifnum\bt@line@cnt=1
3526 \bt@if@signatureline{\bt@tempb}{%
3527 \read\bt@infileb to\bt@tempb
3528 }{}%
3529 \fi
3530 % \end{macrocode}
3531 % Test if the two lines just read are equal, and re-enter the loop:
3532 % \begin{macrocode}
3533 \ifx\bt@tempa\bt@tempb
3534 %<debug> \bt@debug{\bt@tempa -\bt@tempb\space are equal}%
3535 \else
3536 %<*debug>
3537 \bt@debug{|\bt@tempa| - |\bt@tempb| differ!}%
3538 %</debug>
3539 \bt@contfalse
3540 \global\bt@files@difftrue
3541 \fi
3542 \repeat
3543 % \end{macrocode}
3544 % Done with the comparison loop; close the files, close enclosing
3545 % group and
3546 % print result of the comparison (i.\,e., a warning message
3547 % if the files differ):
3548 % \begin{macrocode}
3549 \closein\bt@infilea
3550 \closein\bt@infileb
3551 \egroup
3552 \ifthenelse{\boolean{bt@files@diff}}{%
3553 #3%
3554 }{%
3555 #4%
3556 }%
3557 }
3558 % \end{macrocode}
3559 % \end{macro}
3560
3561 % \begin{macro}{\bt@set@cnt}
3562 % This command will be read from the \File{.aux} file; it sets
3563 % \Com{bt@totalctr} (used by \Com{bt@adjust@label}).
3564 % \begin{macrocode}
3565 \newcommand*\bt@set@cnt[1]{%
3566 %<debug> \bt@debug{setting totalcnt to #1}%
3567 \gdef\bt@totalctr{#1}%
3568 }
3569 % \end{macrocode}
3570 % \end{macro}
3571
3572
3573 %
3574 % ^^A ------------------------------------------------------------
3575 % \subsubsection{Keyval stuff (experimental)}
3576 % ^^A ------------------------------------------------------------
3577 %
3578 % The name `keyval lists' could be misleading, since the
3579 % list may contain a `key' several times (with different values).
3580 % The `key' is just the citation key of the reference, and the
3581 % value is the section label where its reference has been printed.
3582 % Example:
3583 % \begin{verbatim}
3584 % \@elt {ColBenh:93}{Sec:4}\@elt {RouxSmart:95}{Sec:2}
3585 % \@elt {Munt:93}{Sec:1}\@elt {ColBenh:93}{Sec:1}
3586 % \end{verbatim}
3587 %
3588 % \begin{macro}{\bt@old@keyval@list}
3589 % \begin{macrocode}
3590 \newcommand*\bt@keyval@list{}
3591 % \end{macrocode}
3592 % \end{macro}
3593
3594 % \begin{macro}{\bt@kv@add}
3595 % Add the key-value pair |#1|-|#2| to the list \Com{bt@old@keyval@list};
3596 % |#1| is the author key, |#2| the section label. We add this to
3597 % the list in the form \Com{@elt}|{#1}||{#2}|.
3598 % \begin{macrocode}
3599 \newcommand*\bt@kv@add[2]{%
3600 \protected@edef\bt@tempa{\bt@keyval@list}%
3601 \protected@xdef\bt@keyval@list{\noexpand\@elt{#1}{#2}\bt@tempa}%
3602 }
3603 % \end{macrocode}
3604 % \end{macro}
3605
3606 % \begin{macro}{\btCiteSect}
3607 % Here's an example for a user-defined command as a
3608 % front end the \Com{btGetVal} command: Get the label for
3609 % citation key |#1|, and use it along with
3610 % a \Com{cite} command:
3611 % \begin{macrocode}
3612 \DeclareRobustCommand*\btCiteSect[1]{%
3613 \btGetVal{#1}%
3614 \cite{#1} (section\nobreakspace{}\ref{\btretval})%
3615 }
3616 % \end{macrocode}
3617 % \end{macro}
3618
3619 % \begin{macro}{\btRef}
3620 % Another possiblility for a user command:
3621 % Prints the label |#1| as a reference of type |#2|;
3622 % e.\,g.: \Com{btRef}|{Smith:69}||{\pageref}|.
3623 % \begin{macrocode}
3624 \DeclareRobustCommand*\btRef[2]{%
3625 % get section label of #1 from \bt@keyval@list
3626 % reference type is #2
3627 \ifx\bt@keyval@list\@undefined
3628 {\bfseries{???}}%
3629 \else
3630 \bt@get@keyval{#1}{\bt@keyval@list}%
3631 #2{\btretval}%
3632 \fi
3633 }
3634 % \end{macrocode}
3635 % \end{macro}
3636
3637 % \begin{macro}{\btGetVal}
3638 % Sets \Com{btretval}, for later use
3639 % use like, e.g.:
3640 % \begin{verbatim}
3641 % \cite{foo}\btGetVal{foo}
3642 % (\ref{\btretval}, {\itshape\titleref{\btretval}}).
3643 % \end{verbatim}
3644 % \begin{macrocode}
3645 \DeclareRobustCommand*\btGetVal[1]{%
3646 \bt@get@keyval{#1}{\bt@keyval@list}%
3647 }
3648 % \end{macrocode}
3649 % \end{macro}
3650 % \begin{macro}{\bt@print@keyvals}
3651 % |#1| is a list of `keys', |#2| is the value (bib section of the bibitem
3652 % corresponding to `key'). We write the key-value pairs wrapped into a
3653 % command (\Com{bt@keyval@add}) to the .aux file; this command will build up
3654 % a new list in the next run. Note that values could be written twice if
3655 % the user has used `positive' and `all' citation lists for the same
3656 % bibliography. Currently, the command \Com{bt@get@keyval} will
3657 % return only the value of the first key found.
3658 % \begin{macrocode}
3659 \newcommand*\bt@print@keyvals[2]{%
3660 %<debug> \bt@debug{^^J***list is: #1}%
3661 \let\bt@elt\@elt%
3662 \def\@elt##1{%
3663 %<debug> \bt@debug{writing keyval: ##1,#2}%
3664 \protected@write\@auxout{}{%
3665 \string\bt@kv@add{##1}{#2}%
3666 }%
3667 }#1%
3668 \let\@elt\bt@elt
3669 }
3670 % \end{macrocode}
3671 % \end{macro}
3672 %
3673 % \begin{macro}{\bt@get@keyval}
3674 % Search for keys in the list and return the value of the found key
3675 % as \Com{btretval}. This always returns the \emph{last} value found,
3676 % so if a key is stored multiple times in the list,
3677 % the values of the later occurrence will overwrite the values of
3678 % earlier occurrences (consider this when looking at the order of insertion
3679 % in \Com{bt@addto@keyval@list}).
3680 % \begin{macrocode}
3681 \newcommand*\bt@get@keyval[2]{%
3682 \gdef\btretval{???}%
3683 % \end{macrocode}
3684 % First save key to list of `requested' lists;
3685 % only those will be printed as labels later on.
3686 % \begin{macrocode}
3687 \bt@add@elem{#1}{\bt@kv@req@list}%
3688 %% get value of key #1 from list #2
3689 \protected@edef\bt@tempa{#1}%
3690 \bt@elemfalse
3691 \let\bt@elt\@elt%
3692 \def\@elt##1##2{\def\bt@tempb{##1}%
3693 \ifx\bt@tempa\bt@tempb %##2
3694 \gdef\btretval{##2}%
3695 \fi
3696 }%
3697 #2%
3698 \let\@elt\bt@elt
3699 \ifthenelse{\equal{\btretval}{???}}{%
3700 \PackageWarning{bibtopic}{%
3701 Key `#1' not found\MessageBreak in list of cited works%
3702 }%
3703 }{}%
3704 }
3705 % \end{macrocode}
3706 % \end{macro}
3707
3708 % \begin{macro}{\bt@get@label}
3709 % Get value of key |#1| from list |#2|
3710 % \begin{macrocode}
3711 \newcommand*\bt@get@label[2]{%
3712 \protected@edef\bt@tempa{#1}%
3713 \let\bt@elt\@elt%
3714 \def\@elt##1##2{\def\bt@tempb{##1}%
3715 \ifx\bt@tempa\bt@tempb%
3716 ##2
3717 \fi
3718 }%
3719 #2%
3720 \let\@elt\bt@elt
3721 }
3722 % \end{macrocode}
3723 % \end{macro}
3724
3725 % ^^A --------------------------------------------------
3726 % \subsection{User interface}
3727 % ^^A --------------------------------------------------
3728 %
3729 % \begin{environment}{btSect}
3730 % Optional arg |#1| is the bibstyle,
3731 % |#2| is the list of \BibTeX\ files.
3732 % Warn if the optional argument is empty and
3733 % no default \Com{bibliographystyle} has been selected.
3734 % \begin{macrocode}
3735 \newenvironment{btSect}[2][\bt@globalstyle]{%
3736 \ifthenelse{\equal{#1}{}}{%
3737 \PackageWarning{%
3738 bibtopic%
3739 }{%
3740 No \string\bibliographystyle\space given
3741 - \MessageBreak assuming `\bt@defaultstyle'%
3742 }%
3743 \def\bt@globalstyle{\bt@defaultstyle}%
3744 }{}%
3745 % \end{macrocode}
3746 % Define \Com{bt@sect}\Com{romannumeral}\Com{bt@unit@cnt} to
3747 % save the current \Com{bt@cited@list} (similar to what is done
3748 % by \Com{bt@save@list} (via the \File{.aux} file) for different
3749 % \Env{btUnit}s; this is the trivial case where \Com{bt@unit@cnt}
3750 % will always equal one, but since we don't call \Com{bt@save@list}
3751 % when not having \Env{btUnit}s, we have to define \Com{btsecti}
3752 % manually here. We define it only in case it's not defined yet):
3753 % \begin{macrocode}
3754 \expandafter\ifx\csname bt@sect\bt@unit@cnt%
3755 \endcsname\relax
3756 \expandafter\protected@xdef\csname bt@sect%
3757 \bt@unit@cnt\endcsname{\bt@cited@list}%
3758 %<*debug>
3759 \bt@debug{list\bt@unit@cnt{} newly defined as:
3760 \csname bt@sect\bt@unit@cnt\endcsname}%
3761 \else
3762 \bt@debug{list\bt@unit@cnt{} was already defined as:
3763 \csname bt@sect\bt@unit@cnt\endcsname}%
3764 %</debug>
3765 \fi
3766 \stepcounter{btauxfile}%
3767 \bt@info{bibliographystyle is `#1'\MessageBreak
3768 for file `\thebtauxfile .bbl'%
3769 }%
3770 % \end{macrocode}
3771 % ^^A
3772 % Set flag for error checking:
3773 % \begin{macrocode}
3774 \bt@inside@secttrue
3775 \gdef\bt@curr@bib@file{#2}%
3776 \gdef\bt@sect@ref@list{}% +code:bt@sect@ref@listReset;
3777 \bt@change@thb%
3778 \if@filesw
3779 \@bt@write@auxfile{#1}{*}{#2}%
3780 \fi
3781 }{%
3782 \relax
3783 }%
3784 % \end{macrocode}
3785 % \end{environment}
3786 %
3787 % \begin{environment}{btUnit}
3788 % Implements the `logically independent' citation sections.
3789 % Most of the work is done by redefining the \Com{@citex} and
3790 % \Com{bibcite} commands (inside \Com{bt@setcites}).
3791 % \begin{macrocode}
3792 \newenvironment{btUnit}{%
3793 \ifthenelse{\boolean{bt@inside@unit}}{%
3794 \PackageError{%
3795 bibtopic%
3796 }{%
3797 The `btUnit' environment cannot be nested%
3798 }{%
3799 You cannot use a `btUnit' environment inside another^^J%
3800 `btUnit' environment.
3801 }%
3802 }{}%
3803 \global\bt@inside@unittrue
3804 % \end{macrocode}
3805 % Then we write a command to the \File{.aux} file that will change
3806 % the \Com{bibitem} command, and we
3807 % activate the redefinitions of the \Com{@citex} and \Com{nocite}
3808 % commands in case \Package{natbib} hasn't been loaded
3809 % (since it has its own definitions that work with this package as well):
3810 % \begin{macrocode}
3811 \immediate\write\@auxout{%
3812 \string\csname\space change@bibcite\string\endcsname%
3813 }%
3814 \ifthenelse{\not\boolean{bt@natbib}}{%
3815 \bt@setcites
3816 }{}%
3817 % \end{macrocode}
3818 % Unless the \Env{unitcntnoreset} option had been used,
3819 % reset the bibitems counter:
3820 % \changes{v1.0k}{2002/06/11}{%
3821 % Also reset previously forgotten \chCom{bt@save@cnt}
3822 % }
3823 % \begin{macrocode}
3824 \ifthenelse{\not\boolean{bt@part@cont@ctr}}{%
3825 \def\bt@save@cnt{0}%
3826 \ifthenelse{\boolean{bt@natbib}}{%
3827 \setcounter{NAT@ctr}{0}%
3828 }{%
3829 \setcounter{enumiv}{0}% for standard styles
3830 }%
3831 }{}%
3832 % \end{macrocode}
3833 % The entire redefinition stuff with \Com{bibcite} won't work without this extra
3834 % level of indirection (this is again taken from \Package{chapterbib.sty}):
3835 % \begin{macrocode}
3836 \protected@xdef\the@ipfilectr{\bt@unit@cnt}%
3837 % \end{macrocode}
3838 % Then we put the command to empty \Com{bt@cited@list} into the \File{.aux} file,
3839 % and the command to set \Com{@extra@b@citeb}. (This is also the reason why you
3840 % cannot nest several \Env{btUnit} environments.)
3841 % \begin{macrocode}
3842 \immediate\write\@auxout{\string\def\string\bt@cited@list{}^^J%
3843 \string\gdef\string\@extra@binfo{\@extra@b@citeb}}%
3844 }{%
3845 % \end{macrocode}
3846 % \Com{bt@save@list} will save \Com{bt@citedlist} to a list specific to
3847 % the current \Env{btUnit} (using the value of \Env{bt@unit@cnt} to make it unique)
3848 % at the time the \File{.aux} file is read:
3849 % \begin{macrocode}
3850 \immediate\write\@auxout{\string\bt@save@list{\bt@unit@cnt}}
3851 \bt@stepcnt\bt@unit@cnt
3852 \gdef\the@ipfilectr{}%
3853 \immediate\write\@auxout{%
3854 \string\gdef\string\@extra@binfo{\@extra@b@citeb}}%
3855 \global\bt@inside@unitfalse
3856 }
3857 % \end{macrocode}
3858 % \end{environment}
3859 %
3860 % All the following commands do similar stuff: Apart from setting the labels
3861 % for the keyval thing, they all call \Com{bt@change@bibitem} to activate
3862 % our `fake' environments, and then input the \Env{thebibliography}
3863 % environment. The only major difference between them is in setting the
3864 % \Com{@bt@print@\{positive$\mid$all\}@} flags that control printing inside
3865 % \Com{bt@call@item}. \Com{bt@label} is used to make the label commands used
3866 % by the keyval mechanism more flexible.
3867 % ^^A
3868 % \changes{v1.0b}{1999/09/20}{%
3869 % Added the \chCom{bt@curr@...} commands to the \chCom{btPrint...} commands
3870 % }
3871 % ^^A
3872 % \begin{macro}{\btPrintCited}
3873 % \begin{macrocode}
3874 \newcommand*\bt@label@sec{\label}%
3875 \newcommand*\btPrintCited{%
3876 \ifthenelse{\boolean{bt@inside@sect}}{%
3877 \protected@edef\bt@curr@line{\the\inputlineno}%
3878 \def\bt@curr@cmd{\string\btPrintCited}%
3879 \bt@stepcnt\bt@internal@sect@cnt%
3880 \bt@print@citedtrue\bt@print@allfalse
3881 \bt@label@sec{Sec:\bt@internal@sect@cnt}%
3882 \bt@change@bibitem
3883 \bt@input@or@warn{\thebtauxfile}%
3884 % \end{macrocode}
3885 % For each item in \Com{bt@sect@ref@list}, write a \Com{bt@kv@add}
3886 % into the \File{.aux} file:
3887 % \begin{macrocode}
3888 \bt@print@keyvals{\bt@sect@ref@list}{%
3889 Sec:\bt@internal@sect@cnt
3890 }%
3891 }{%
3892 \bt@sect@err{btSect}{\btPrintCited}%
3893 }%
3894 }
3895 % \end{macrocode}
3896 % \end{macro}
3897 %
3898 % \begin{macro}{\btPrintNotCited}
3899 % \begin{macrocode}
3900 \newcommand*\btPrintNotCited{%
3901 \ifthenelse{\boolean{bt@inside@sect}}{%
3902 \protected@edef\bt@curr@line{\the\inputlineno}%
3903 \def\bt@curr@cmd{\string\btPrintNotCited}%
3904 \bt@stepcnt\bt@internal@sect@cnt
3905 \bt@print@citedfalse\bt@print@allfalse
3906 \bt@label@sec{Sec:\bt@internal@sect@cnt}%
3907 \bt@change@bibitem
3908 \bt@input@or@warn{\thebtauxfile}%
3909 }{%
3910 \bt@sect@err{btSect}{\btPrintNotCited}%
3911 }%
3912 }
3913 % \end{macrocode}
3914 % \end{macro}
3915 %
3916 % \begin{macro}{\btPrintAll}
3917 % \begin{macrocode}
3918 \newcommand*\btPrintAll{%
3919 \ifthenelse{\boolean{bt@inside@sect}}{%
3920 \protected@edef\bt@curr@line{\the\inputlineno}%
3921 \def\bt@curr@cmd{\string\btPrintAll}%
3922 \bt@stepcnt\bt@internal@sect@cnt
3923 \bt@print@citedfalse\bt@print@alltrue
3924 \bt@label@sec{Sec:\bt@internal@sect@cnt}%
3925 \bt@change@bibitem
3926 \bt@input@or@warn{\thebtauxfile}%
3927 \bt@print@keyvals{\bt@sect@ref@list}%
3928 {Sec:\bt@internal@sect@cnt}%
3929 }{%
3930 \bt@sect@err{btSect}{\btPrintAll}%
3931 }%
3932 }
3933 % \end{macrocode}
3934 % \end{macro}
3935 %
3936 % \begin{environment}{bibtopics}
3937 % The bibtopics environment of bibtopics.sty, version November '97
3938 % \begin{macrocode}
3939 \newenvironment{bibtopics}[2]{%
3940 \begin{btSect}[#1]{#2}%
3941 \btPrintAll
3942 }{%
3943 \end{btSect}%
3944 }
3945 % \end{macrocode}
3946 % \end{environment}
3947 %
3948 % \begin{environment}{bibunit}
3949 % The obsolete bibunit command.
3950 %
3951 % Its syntax:
3952 % \begin{verbatim}
3953 % \begin{bibunit}[plain]
3954 % \nocite{*}
3955 % \putbib[ArtDansRev]
3956 % \end{bibunit}
3957 % \end{verbatim}
3958 % This implementation needn't share all the features of
3959 % \Env{btSect} (like preparing the lists of cited authors)
3960 % because it's only for compatibility with existing documents.
3961 % \begin{macrocode}
3962 \newcommand\bt@bibstyle{}
3963 \newcommand\bt@citation{}
3964 \newcommand\bt@bibdata{}
3965 \newenvironment{bibunit}[1][\bt@globalstyle]{%
3966 \ifx#1\@empty
3967 \PackageWarning{%
3968 bibtopic%
3969 }{%
3970 No \string\bibliographystyle\space given
3971 - \MessageBreak assuming `\bt@defaultstyle'%
3972 }%
3973 \def\bt@globalstyle{\bt@defaultstyle}%
3974 \fi
3975 \def\bt@bibstyle{#1}%
3976 \def\nocite##1{\def\bt@citation{##1}}%
3977 \def\cite##1{\def\bt@citation{##1}}%
3978 \gdef\putbib[##1]{\gdef\bt@bibdata{##1}}%
3979 \stepcounter{btauxfile}%
3980 }{%
3981 \bt@change@thb
3982 \if@filesw
3983 \@bt@write@auxfile{\bt@bibstyle}{\bt@citation}{\bt@bibdata}%
3984 \fi
3985 % \end{macrocode}
3986 % Then we call \Com{btPrintAll}:
3987 % \begin{macrocode}
3988 \bt@inside@secttrue
3989 \btPrintAll
3990 }
3991 % \end{macrocode}
3992 % \end{environment}
3993 %
3994 %
3995 % ^^A --------------------------------------------------
3996 % \subsection{Warnings and error messages}\label{sec:PackageWarnings}
3997 % ^^A --------------------------------------------------
3998 %
3999 % \begin{macro}{\bt@bibitemcheck}
4000 % Warn if no bibitem matching the current specification
4001 % (cited\slash not cited) have been found in this
4002 % \Env{thebibliography} environment.
4003 % ^^A
4004 % \changes{v1.0b}{1999/09/20}{%
4005 % Improved the error message by adding the \chCom{bt@curr@...} commands
4006 % }
4007 % ^^A
4008 % \begin{macrocode}
4009 \newcommand*\bt@bibitemcheck{%
4010 \ifthenelse{\not\boolean{bt@found@item}}{%
4011 \PackageWarningNoLine{%
4012 bibtopic%
4013 }{%
4014 No appropriate bibitems found for command\MessageBreak %
4015 \bt@curr@cmd\space on line \bt@curr@line% +code:bt@curr@cmd;
4016 }%
4017 }{}%
4018 }
4019 % \end{macrocode}
4020 % \end{macro}
4021 %
4022 % \begin{macro}{\bt@sect@err}
4023 % Give an error message saying that a command |#2| is being used
4024 % outside of the environment |#1| it belongs to:
4025 % \begin{macrocode}
4026 \newcommand*\bt@sect@err[2]{%
4027 \PackageError{%
4028 bibtopic%
4029 }{%
4030 You can't use `\string#2' outside of `#1'%
4031 }{%
4032 See the documentation on the `\string#2' command\MessageBreak
4033 in `bibtopic.dvi' for details.
4034 }%
4035 }
4036 % \end{macrocode}
4037 % \end{macro}
4038
4039
4040 % \begin{macro}{\bt@bibtex@warning}
4041 % Instead of \LaTeX's silent \ErrMessage{No file xxx.bbl}, we issue
4042 % a more obtrusive warning. Called by \Com{bt@files@warnings}.
4043 % \begin{macrocode}
4044 \newcommand*\bt@bibtex@warning[1]{%
4045 \PackageWarningNoLine{%
4046 bibtopic%
4047 }{%
4048 Please (re)run BibTeX on the file(s):%
4049 \expandafter\MessageBreak#1%
4050 and after that rerun LaTeX%
4051 }%
4052 }
4053 % \end{macrocode}
4054 % \end{macro}
4055
4056
4057 % \begin{macro}{\bt@files@warnings}
4058 % Print warning about undefined \Com{harvarditem} commands, and about
4059 % files being outdated.
4060 % \begin{macrocode}
4061 \newcommand*\bt@files@warnings{%
4062 \ifthenelse{\boolean{bt@harvard@errs}}{%
4063 \PackageError{%
4064 bibtopic%
4065 }{%
4066 Your command \string\harvarditem\space was ignored%
4067 }{%
4068 `bibtopic' currently supports the `\string\harvarditem'
4069 command^^J
4070 only in connection with the `natbib' package. So either^^J%
4071 load this package, or change the `\string\citationstyle' command
4072 to some^^J%
4073 non-harvard style.^^J%
4074 If you hit RETURN now, some of your bibliographies will be empty.
4075 }%
4076 }{}%
4077 \ifthenelse{\boolean{bt@overridden@numargs}}{%
4078 \ifthenelse{\boolean{bt@warn@override}}{%
4079 \PackageWarningNoLine{%
4080 bibtopic%
4081 }{%
4082 The numerical argument in some `\string\bibitem' commands^^J%
4083 has been ignored. Using one of the package options^^J%
4084 `overridenumbers' or `dontoverridenumbers' will make^^J%
4085 this warning go away.^^J%
4086 Please see the documentation on these options^^J%
4087 in `bibtopic.dvi' for more details.
4088 }%
4089 }{}%
4090 }{}%
4091 \ifthenelse{\equal{\bt@warn@files}{}}{%
4092 \relax
4093 }{%
4094 \bt@mk@warning@list{\bt@warn@files}%
4095 \bt@bibtex@warning{\the\@temptokena}%
4096 % \end{macrocode}
4097 % \changes{v1.0k}{2002/06/11}{%
4098 % Disable the `rerun latex' message when .bbl files are missing to avoid confusion
4099 % }
4100 % Also disable the `rerun latex' message in this case, since multiple messages would
4101 % confuse the user:
4102 % \begin{macrocode}
4103 \def\bt@helpctr{\bt@totalctr}%
4104 }%
4105 }
4106 % \end{macrocode}
4107 % \end{macro}
4108
4109
4110 % \begin{macro}{\bt@input@or@warn}
4111 % Input a \File{.bbl} file if it exists; else,
4112 % add it to our list of missing\slash outdated files.
4113 % \begin{macrocode}
4114 \newcommand*\bt@input@or@warn[1]{%
4115 \IfFileExists{#1.bbl}%
4116 {%
4117 \input#1.bbl%
4118 }{%
4119 \bt@if@elem{#1}{\bt@warn@files}{%
4120 \relax
4121 }{%
4122 \PackageWarningNoLine{%
4123 bibtopic%
4124 }{%
4125 No file #1.bbl%
4126 }%
4127 % \end{macrocode}
4128 % Skip the extra warning using \Com{bt@warn@files} if \Env{normalwarnings} is active:
4129 % \begin{macrocode}
4130 \ifbt@normalwarnings
4131 \else
4132 \bt@append@list{#1}{\bt@warn@files}%
4133 \fi
4134 }%
4135 }%
4136 }%
4137 % \end{macrocode}
4138 % \end{macro}
4139
4140
4141 % \begin{macro}{\bt@warn@outdated}
4142 % Append |#1| to \Com{bt@warn@files} just in case it's not
4143 % yet in this list:
4144 % \begin{macrocode}
4145 \newcommand*\bt@warn@outdated[1]{%
4146 \bt@if@elem{#1}{\bt@warn@files}{%
4147 \relax
4148 }{%
4149 \bt@infoNoLine{Marking #1.bbl as outdated}%
4150 \bt@append@list{#1}{\bt@warn@files}%
4151 }%
4152 \ifthenelse{\not\boolean{bt@natbib}}{%
4153 % \end{macrocode}
4154 % Don't continue reading, since this would only lead to errors anyway
4155 % (heuristic):
4156 % \begin{macrocode}
4157 \global\let\bt@item\relax
4158 \global\let\endbt@item\relax
4159 }{}%
4160 }%
4161 % \end{macrocode}
4162 % \end{macro}
4163 %
4164 % \begin{macrocode}
4165 %</package>
4166 % \end{macrocode}
4167 % \iffalse meta-comment
4168 % ^^A --- BibTeX file articles.bib ---
4169 %
4170 %<*articles.bib>
4171 The following entry is an example for what's allowed by
4172 BibTeX syntax (see btxdoc.dvi).
4173
4174 @incollection
4175 (
4176 RouxSmart:95
4177 ,
4178 author = "M. Roux and J. Smart",
4179 title = "A Model of Medical Knowledge Representation, Application
4180 to the Reports Analysis of Descriptive Pathology",
4181 booktitle = "Methods of Information in Medecine",
4182 note = {\`A para\^{\i}tre},
4183 publisher = "Schattauer",
4184 address = "Holland",
4185 year = 1995
4186 )
4187
4188 @article{Schwind:96,
4189 author = {Camilla B. Schwind},
4190 title = {Knowledge Based Language Tutoring},
4191 journal = {Computer Assisted Language Learning},
4192 publisher = {Svets},
4193 year = 1996,
4194 note = {\`A para\^{\i}tre}
4195 }
4196
4197 %</articles.bib>
4198 %
4199 % ^^A --- BibTeX file books.bib ---
4200 %
4201 %<*books.bib>
4202 @book{ColBenh:93,
4203 editor = "Fr\'ed\'eric Benhamou and Alain Colmerauer" ,
4204 title = "Constraint Logic programming, Selected Research",
4205 publisher = "MIT Press",
4206 year = 1993
4207 }
4208
4209 @book{Munt:93,
4210 author = {Tra{\"\i}an Muntean},
4211 title = {Puces tr\`es performantes},
4212 publisher = {Hatier},
4213 address = {Paris},
4214 series = {Terres du futur, Les Editions UNESCO},
4215 year = 1993,
4216 }
4217
4218 %</books.bib>
4219 %
4220 % ^^A --- .bbl files produced from .bib files above ---
4221 %
4222 %<*bibtopic2.bbl>
4223 \begin{thebibliography}{1}
4224
4225 \bibitem{RouxSmart:95}
4226 M.~Roux and J.~Smart.
4227 \newblock A model of medical knowledge representation, application to the
4228 reports analysis of descriptive pathology.
4229 \newblock In {\em Methods of Information in Medecine}. Schattauer, Holland,
4230 1995.
4231 \newblock \`A para\^{\i}tre.
4232
4233 \bibitem{Schwind:96}
4234 Camilla~B. Schwind.
4235 \newblock Knowledge based language tutoring.
4236 \newblock {\em Computer Assisted Language Learning}, 1996.
4237 \newblock \`A para\^{\i}tre.
4238
4239 \end{thebibliography}
4240 %</bibtopic2.bbl>
4241 %<*bibtopic1.bbl>
4242 \begin{thebibliography}{Mun93}
4243
4244 \bibitem[BC93]{ColBenh:93}
4245 Fr\'ed\'eric Benhamou and Alain Colmerauer, editors.
4246 \newblock {\em Constraint Logic programming, Selected Research}.
4247 \newblock MIT Press, 1993.
4248
4249 \bibitem[Mun93]{Munt:93}
4250 Tra{\"\i}an Muntean.
4251 \newblock {\em Puces tr\`es performantes}.
4252 \newblock Terres du futur, Les Editions UNESCO. Hatier, Paris, 1993.
4253
4254 \end{thebibliography}
4255 %</bibtopic1.bbl>
4256 %
4257 % ^^A --- sample .tex file including the bibliographies ---
4258 %
4259 %<*sample.tex>
4260 \documentclass[10pt]{article}
4261 \usepackage{bibtopic}
4262 \begin{document}
4263 \bibliographystyle{alpha}
4264
4265 \section{Testing}
4266 Let's cite all the books: \cite{ColBenh:93} and
4267 \cite{Munt:93}; and an article: \cite{RouxSmart:95}.
4268
4269 \begin{btSect}{books}
4270 \section{References from books}
4271 \btPrintCited
4272 \end{btSect}
4273
4274 \begin{btSect}[plain]{articles}
4275 \section{References from articles}
4276 \btPrintCited
4277
4278 \section{Articles not cited}
4279 \btPrintNotCited
4280 \end{btSect}
4281 \end{document}
4282 %</sample.tex>
4283 %
4284 % \fi
4285 % ^^A \typeout{^^Juncomment FINALE before releasing!!!^^J}
4286 % \Finale
4287 \endinput
4288