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