| blob | 6b2ea19e2dae951772d77714e834f7348ba0af57 |
1 % \iffalse meta-comment
2 %
3 % Copyright 1993-2016
4 % The LaTeX3 Project and any individual authors listed elsewhere
5 % in this file.
6 %
7 % This file is part of the LaTeX base system.
8 % -------------------------------------------
9 %
10 % It may be distributed and/or modified under the
11 % conditions of the LaTeX Project Public License, either version 1.3c
12 % of this license or (at your option) any later version.
13 % The latest version of this license is in
14 % http://www.latex-project.org/lppl.txt
15 % and version 1.3c or later is part of all distributions of LaTeX
16 % version 2005/12/01 or later.
17 %
18 % This file has the LPPL maintenance status "maintained".
19 %
20 % The list of all files belonging to the LaTeX base distribution is
21 % given in the file `manifest.txt'. See also `legal.txt' for additional
22 % information.
23 %
24 % The list of derived (unpacked) files belonging to the distribution
25 % and covered by LPPL is defined by the unpacking scripts (with
26 % extension .ins) which are part of the distribution.
27 %
28 % \fi
29 % \iffalse
30 %%% From File: ltbibl.dtx
31 %
32 %<*driver>
33 % \fi
34 \ProvidesFile{ltbibl.dtx}
35 [2004/02/15 v1.1q LaTeX Kernel (Bibliography)]
36 % \iffalse
37 \documentclass{ltxdoc}
38 \GetFileInfo{ltbibl.dtx}
39 \title{\filename}
40 \date{\filedate}
41 \author{%
42 Johannes Braams\and
43 David Carlisle\and
44 Alan Jeffrey\and
45 Leslie Lamport\and
46 Frank Mittelbach\and
47 Chris Rowley\and
48 Rainer Sch\"opf}
50 \begin{document}
51 \MaintainedByLaTeXTeam{latex}
52 \maketitle
53 \DocInput{\filename}
54 \end{document}
55 %</driver>
56 % \fi
57 %
58 %
59 % \section{Bibliography Generation}
60 %
61 % A bibliography is created by the |thebibliography| environment, which
62 % generates a title such as ``References'', and a list of entries.
63 % The BIB\TeX{} program will create a file containing such an
64 % environment, which will be read in by the |\bibliography| command.
65 % With BIB\TeX, the following commands will be used.
66 %
67 % \DescribeMacro{\bibliography}
68 % |\bibliography|\marg{file1,file2, \ldots ,filen} : specifies
69 % the bibdata files. Writes a |\bibdata| entry on the |.aux| file
70 % and tries to read in |mainfile.bbl|.
71 %
72 % \DescribeMacro{\bibliographystyle}
73 % |\bibliographystyle|\marg{style} :
74 % Writes a |\bibstyle| entry on the |.aux| file.
75 %
76 % \DescribeEnv{thebibliography}
77 % The |thebibliography| environment is a list environment. To save the
78 % use of an extra counter, it should use |enumiv| as the item
79 % counter.
80 % Instead of using |\item|, items in the bibliography are produced by
81 % the following commands:\\
82 % |\bibitem|\marg{name} : Produces a numbered entry cited as
83 % \meta{name}.\\
84 % |\bibitem|\oarg{label}\marg{name} : Produces an entry labeled by
85 % \meta{Label} and cited by \meta{name}.
86 %
87 % The former is used for bibliographies with citations like [1], [2],
88 % etc.;
89 % the latter is used for citations like [Knuth82].
90 %
91 % The document class must define the thebibliography environment. This
92 % environment has a single argument, which is the widest bibliography
93 % label-- e.g., if the [Knuth67] is the widest entry, then this
94 % argument will be Knuth67. The |\thebibliography| command must begin
95 % a list environment, which the |\endthebibliography| command ends.
96 %
97 % \DescribeMacro{\cite}
98 % Entries are cited by the command |\cite|\marg{name}.
99 %
100 % \DescribeMacro{\nocite}
101 % |\nocite|\marg{citations}
102 % puts information on the |.aux| file that causes
103 % \BibTeX{} to include the \marg{citations} list in the bibliography,
104 % but puts nothing in the text.
105 %
106 % |\nocite{*}| is special: it tells \BibTeX{} to put the whole of a
107 % collection of references into the bibiography.
108 %
109 % \StopEventually{}
110 %
111 %
112 % \changes{v1.0a}{1994/03/31}{Initial version of ltidxbib.dtx,
113 % split from ltherest.dtx}
114 % \changes{v1.1a}{1994/05/19}{Initial version of ltbibl.dtx,
115 % split from ltidxbib.dtx}
116 % \changes{v1.1b}{1994/05/21}{Use new warning commands}
117 % \changes{v1.1c}{1994/11/10}{Fix \cs{nocite}\texttt{\char`\{*\char`\}}}
118 %
119 % \begin{macrocode}
120 %<*2ekernel>
121 \message{bibliography,}
122 % \end{macrocode}
123 %
124 %
125 % \begin{oldcomments}
126 % PARAMETERS
127 %
128 % \@cite : A macro such that \@cite{LABEL1,LABEL2}{NOTE}
129 % produces the output for a \cite[NOTE]{FOO1,FOO2} command,
130 % where entry FOOi is defined by \bibitem[LABELi]{FOOi}.
131 % The switch @tempswa is true if the optional NOTE argument
132 % is present.
133 % The default definition is :
134 % \@cite{LABELS}{NOTE} ==
135 % BEGIN [LABELS
136 % IF @tempswa = T THEN , NOTE FI
137 % ]
138 % END
139 %
140 % \@biblabel : A macro to produce the label in the bibliography
141 % entry. For \bibitem[LABEL]{NAME}, the label is
142 % generated by \@biblabel{LABEL}. It has the default
143 % definition \@biblabel{LABEL} -> [LABEL].
144 % CONVENTION
145 %
146 % \b@FOO : The name or number of the reference created by \cite{FOO}
147 % E.g., if \cite{FOO} -> [17] , then \b@FOO -> 17.
148 %
149 % \end{oldcomments}
150 %
151 % \begin{macro}{\bibitem}
152 % \changes{v1.1g}{1995/05/08}{Removed unnecessary braces}
153 % \begin{macrocode}
154 \def\bibitem{\@ifnextchar[\@lbibitem\@bibitem}
155 % \end{macrocode}
156 % \end{macro}
157 %
158 % \begin{macro}{\@lbibitem}
159 % \changes{LaTeX2.09}{1992/02/26}{Added \cs{hfill} to restore
160 % left-alignment of bibliography labels in alpha style}
161 % \begin{macrocode}
162 \def\@lbibitem[#1]#2{\item[\@biblabel{#1}\hfill]\if@filesw
163 {\let\protect\noexpand
164 \immediate
165 \write\@auxout{\string\bibcite{#2}{#1}}}\fi\ignorespaces}
166 % \end{macrocode}
167 % \end{macro}
168 %
169 %
170 % \begin{macro}{\@bibitem}
171 % \changes{LaTeX2.09}{1991/11/13}{Changed counter enumi to enumiv,
172 % as it says in the comment above}
173 % \changes{LaTeX2.09}{1992/01/10}{Changed \cs{c@enumiv} to \cs{value}
174 % of \cs{@listctr}}
175 % \begin{macrocode}
176 \def\@bibitem#1{\item\if@filesw \immediate\write\@auxout
177 {\string\bibcite{#1}{\the\value{\@listctr}}}\fi\ignorespaces}
178 % \end{macrocode}
179 % \end{macro}
180 %
181 % \begin{macro}{\bibcite}
182 % \changes{v1.1f}{1995/04/24}
183 % {Make \cs{@onlypreamble} /1388.}
184 % \changes{v1.1h}{1995/06/19}
185 % {Call \cs{@newl@bel} so repeated keys produce better warning.}
186 % \changes{v1.1i}{1995/07/14}
187 % {Remove \cs{@onlypreamble} so still defined in new \cs{enddocument}}
188 % \begin{macrocode}
189 \def\bibcite{\@newl@bel b}
190 % \end{macrocode}
191 % \end{macro}
192 %
193 % \begin{macro}{\citation}
194 % \begin{macrocode}
195 \let\citation\@gobble
196 % \end{macrocode}
197 % \end{macro}
198 %
199 % \begin{macro}{\cite}
200 % \changes{v1.1j}{1995/10/16}{(DPC) Make robust}
201 % \begin{macrocode}
202 \DeclareRobustCommand\cite{%
203 \@ifnextchar [{\@tempswatrue\@citex}{\@tempswafalse\@citex[]}}
204 % \end{macrocode}
205 % \end{macro}
206 %
207 % \begin{macro}{\@citex}
208 % |\penalty\@m| added to definition of |\@citex| to allow a line
209 % break after the `,' in citations like [Jones80,Smith77]
210 % (Added 23 Oct 86)
211 %
212 % space added after the `,' (21 Nov 87)
213 %
214 % \changes{LaTeX2.09}{1991/10/25}
215 % {added \cs{reset@font}, suggested by Bernd Raichle.}
216 % \changes{LaTeX2.09}{1991/11/06}
217 % {added code to remove a leading blank}
218 % \changes{LaTeX2.09}{1992/08/14}
219 % {added missing argument braces around \cs{hbox},
220 % found by Ed Sznyter}
221 % \changes{LaTeX2.09}{1992/08/17}
222 % {simplified code for removing leading blanks in
223 % citation key (proposed by Frank Jensen and
224 % Kresten Krab Thorup)}
225 % \changes{LaTeX2.09}{1993/08/06}
226 % {Moved writing to .aux file in loop over citation keys
227 % so that leading blanks are removed there as well.}
228 % \changes{v1.0c}{1994/05/05}{Set switch for warning and end of run.}
229 % \changes{v1.1e}{1995/04/24}
230 % {Add \cs{mbox} to undefined case: latex/1239.}
231 % \changes{v1.1g}{1995/05/08}{Use \cs{@firstofone}}
232 % \changes{v1.1k}{1995/10/20}{Removed refundefined flag}
233 % \changes{v1.1l}{1995/12/07}{Restored name of \cs{G@refundefinedtrue}}
234 % \changes{v1.1m}{1997/04/24}{\cs{@empty} to avoid primitive
235 % error on empty cite keys. latex/2432}
236 % \changes{v1.1n}{2002/12/13}{Added \cs{leavevmode} in case citation
237 % is at start of paragraph (pr/3486)}
238 % \begin{macrocode}
239 \def\@citex[#1]#2{\leavevmode
240 \let\@citea\@empty
241 \@cite{\@for\@citeb:=#2\do
242 {\@citea\def\@citea{,\penalty\@m\ }%
243 \edef\@citeb{\expandafter\@firstofone\@citeb\@empty}%
244 \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
245 % \end{macrocode}
246 % Using |\hbox| instead of |\mbox| is fine because of the
247 % |\leavevmode| above. In fact the use of a box around the citation
248 % contents is more than questionable in my view (FMi), but within
249 % 2e I have to keep that for compatibility reasons as it would
250 % probably change too many existing documents. Its main reason is
251 % to avoid hyphenation of labels such as [FOOB89] into [FOO- B89]
252 % so in certain styles it makes sense; but, for example, in author
253 % year citations it becomes more than questionable.
254 %
255 % So Chris added yet another hook here, as suggested by, at least,
256 % Donald Arsenau. Note that this one is inside the first argument
257 % of the |\@cite| hook.
258 % This decouples the top-level typesetting of the citation from
259 % the details of the other business conducted here. All this really
260 % needs a complete rethink to get the right modularity.
261 %
262 % \changes{v1.1q}{2004/02/15}{Changed to use a hook with default
263 % value \cs{hbox}}
264 % \begin{macrocode}
265 \@ifundefined{b@\@citeb}{\hbox{\reset@font\bfseries ?}%
266 \G@refundefinedtrue
267 \@latex@warning
268 {Citation `\@citeb' on page \thepage \space undefined}}%
269 {\@cite@ofmt{\csname b@\@citeb\endcsname}}}}{#1}}
270 % \end{macrocode}
271 % \end{macro}
272 %
273 %
274 % \begin{macro}{\bibdata}
275 % \begin{macro}{\bibstyle}
276 % \begin{macrocode}
277 \let\bibdata=\@gobble
278 \let\bibstyle=\@gobble
279 % \end{macrocode}
280 % \end{macro}
281 % \end{macro}
282 %
283 %
284 % \begin{macro}{\bibliography}
285 % \changes{LaTeX2e}{1994/01/18}
286 % {Use \cs{@input@} so include files are listed.}
287 % \begin{macrocode}
288 \def\bibliography#1{%
289 \if@filesw
290 \immediate\write\@auxout{\string\bibdata{#1}}%
291 \fi
292 \@input@{\jobname.bbl}}
293 % \end{macrocode}
294 % \end{macro}
295 %
296 % \begin{macro}{\bibliographystyle}
297 % \changes{v1.1d}{1994/12/09}{(DPC) Allow use in preamble.}
298 % \begin{macrocode}
299 \def\bibliographystyle#1{%
300 \ifx\@begindocumenthook\@undefined\else
301 \expandafter\AtBeginDocument
302 \fi
303 {\if@filesw
304 \immediate\write\@auxout{\string\bibstyle{#1}}%
305 \fi}}
306 % \end{macrocode}
307 % \end{macro}
308 %
309 %
310 % \begin{macro}{\nocite}
311 % (Added 14 Jun 85)
312 % \changes{v1.1c}{1994/11/10}{Fix \cs{nocite}\texttt{\char`\{*\char`\}}}
313 %
314 % This puts information on the |.aux| file that causes
315 % \BibTeX{} to include the citation list in the bibliography,
316 % but puts nothing in the text.
317 %
318 % RmS 93/08/06: Made loop for |\nocite| like that for |\@citex|,
319 % to get rid of leading spaces.
320 % \changes{v1.0b}{1994/05/03}{Make \cs{nocite} issue a warning
321 % for an undefined citation key.}
322 % \changes{v1.0c}{1994/05/05}{Do not write page number in
323 % \cs{nocite} warning message.}
324 % \changes{v1.0c}{1994/05/05}{Set switch for warning and end of run.}
325 % \changes{v1.1g}{1995/05/08}{Use \cs{@firstofone}}
326 % \changes{v1.1k}{1995/10/20}{Removed refundefined flag}
327 % \begin{macrocode}
328 \def\nocite#1{\@bsphack
329 % \end{macrocode}
330 % With the implementation designed already in \LaTeX\,2.09 the
331 % |\nocite| command will not work before |\begin{document}| since
332 % it tries to write to the |.aux| file which is not open before
333 % that point. As a result the ``reference'' will appear on the
334 % terminal and nothing else will happen.
335 %
336 % This would be easy to fix, but then a document using the fix will
337 % silently fail on an older release of \LaTeX{}, missing all
338 % citations done with |\nocite|. Thus we do only generate an error
339 % message and leave the fix for a \LaTeXe{} successor.
340 %
341 % \changes{v1.1o}{2003/05/18}{Check if we are after \cs{document}}
342 % \changes{v1.1p}{2004/01/04}{Changed error message}
343 % \begin{macrocode}
344 \ifx\@onlypreamble\document
345 % \end{macrocode}
346 % Since we are after |\begin{document}| we can do the citations:
347 % \begin{macrocode}
348 \@for\@citeb:=#1\do{%
349 \edef\@citeb{\expandafter\@firstofone\@citeb}%
350 \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
351 \@ifundefined{b@\@citeb}{\G@refundefinedtrue
352 \@latex@warning{Citation `\@citeb' undefined}}{}}%
353 \else
354 % \end{macrocode}
355 % But before |\begin{document}| we raise an error message:
356 % \begin{macrocode}
357 \@latex@error{Cannot be used in preamble}\@eha
358 % \end{macrocode}
359 % Without the compatibility problems we could fix the problem as follows:
360 % \begin{macrocode}
361 % \AtBeginDocument{\nocite{#1}}
362 \fi
363 \@esphack}
364 % \end{macrocode}
365 % Since |\nocite{*}| should not produce a warning about undefined
366 % citation keys (seee PR 557), we need to set the control sequence
367 % `|\b@*|' to something other than |\relax|. As a result |\cite{*}|
368 % will not warn either (but that never worked with \BibTeX{} in the
369 % first place).
370 % \begin{macrocode}
371 \expandafter\let\csname b@*\endcsname\@empty
372 % \end{macrocode}
373 % \end{macro}
374 %
375 %
376 % \subsection{Default definitions}
377 %
378 % This hook determines the `relative formatting' of the two logical
379 % parts of a citation with comment.
380 % \begin{macro}{\@cite}
381 % \begin{macrocode}
382 \def\@cite#1#2{[{#1\if@tempswa , #2\fi}]}
383 % \end{macrocode}
384 % \end{macro}
385 %
386 % \begin{macro}{\@cite@ofmt}
387 % \changes{v1.1q}{2004/02/15}{Added hook with default value \cs{hbox}}
388 % This is, in general, a command that appears to have one argument
389 % whose value is, in the kernel, a single cs whose name is the
390 % expansion of |b@\@citeb|; the expansion of this cs will
391 % typically be some hmode material that produces the detailed
392 % typeset form of just the citations themselves.
393 % \begin{macrocode}
394 \let\@cite@ofmt\hbox
395 % \end{macrocode}
396 % \end{macro}
397 %
398 % \begin{macro}{\@biblabel}
399 % \changes{LaTeX2.09}{1992/01/14}{removed \cs{hfill}}
400 % \begin{macrocode}
401 \def\@biblabel#1{[#1]}
402 %</2ekernel>
403 % \end{macrocode}
404 % \end{macro}
405 %
406 % \Finale
407 %