summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltbibl.dtx
blob: 7f5066542f3c1700093cb932ef2662fb14731d3b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
% \iffalse meta-comment
%
% Copyright (C) 1993-2021
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
% \iffalse
%%% From File: ltbibl.dtx
%
%<*driver>
% \fi
\ProvidesFile{ltbibl.dtx}
             [2020/12/10 v1.1s LaTeX Kernel (Bibliography)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltbibl.dtx}
\title{\filename}
\date{\filedate}
 \author{%
  Johannes Braams\and
  David Carlisle\and
  Alan Jeffrey\and
  Leslie Lamport\and
  Frank Mittelbach\and
  Chris Rowley\and
  Rainer Sch\"opf}

\begin{document}
 \MaintainedByLaTeXTeam{latex}
 \maketitle
 \DocInput{\filename}
\end{document}
%</driver>
% \fi
%
%
% \section{Bibliography Generation}
%
%  A bibliography is created by the |thebibliography| environment, which
%  generates a title such as ``References'', and a list of entries.
%  The BIB\TeX{} program will create a file containing such an
%  environment, which will be read in by the |\bibliography| command.
%  With BIB\TeX, the following commands will be used.
%
% \DescribeMacro{\bibliography}
%  |\bibliography|\marg{file1,file2, \ldots ,filen} : specifies
%     the bibdata files.  Writes a |\bibdata| entry on the |.aux| file
%     and tries to read in |mainfile.bbl|.
%
% \DescribeMacro{\bibliographystyle}
%  |\bibliographystyle|\marg{style} :
%     Writes a |\bibstyle| entry on the |.aux| file.
%
% \DescribeEnv{thebibliography}
%  The |thebibliography| environment is a list environment.  To save the
%  use of an extra counter, it should use  |enumiv|  as the item
%  counter.
%  Instead of using |\item|, items in the bibliography are produced by
%  the  following commands:\\
%    |\bibitem|\marg{name}    : Produces a numbered entry cited as
%    \meta{name}.\\
%    |\bibitem|\oarg{label}\marg{name} : Produces an entry labeled by
%    \meta{Label} and cited by \meta{name}.
%
%  The former is used for bibliographies with citations like [1], [2],
%  etc.;
%  the latter is used for citations like [Knuth82].
%
%  The document class must define the thebibliography environment.  This
%  environment has a single argument, which is the widest bibliography
%  label-- e.g., if the [Knuth67] is the widest entry, then this
%  argument will be Knuth67.  The |\thebibliography| command must begin
%  a list  environment, which the |\endthebibliography| command ends.
%
% \DescribeMacro{\cite}
%  Entries are cited by the command |\cite|\marg{name}.
%
% \DescribeMacro{\nocite}
% |\nocite|\marg{citations}
% puts information on the |.aux| file that causes
% \BibTeX{} to include the \marg{citations} list in the bibliography,
% but puts nothing in the text.
%
% |\nocite{*}| is special: it tells \BibTeX{} to put the whole of a
% collection of references into the bibliography.
%
% \StopEventually{}
%
%
% \changes{v1.0a}{1994/03/31}{Initial version of ltidxbib.dtx,
%                             split from ltherest.dtx}
% \changes{v1.1a}{1994/05/19}{Initial version of ltbibl.dtx,
%                             split from ltidxbib.dtx}
% \changes{v1.1b}{1994/05/21}{Use new warning commands}
% \changes{v1.1c}{1994/11/10}{Fix \cs{nocite}\texttt{\char`\{*\char`\}}}
%
%    \begin{macrocode}
%<*2ekernel>
\message{bibliography,}
%    \end{macrocode}
%
%
% \begin{oldcomments}
%  PARAMETERS
%
%   \@cite   : A macro such that \@cite{LABEL1,LABEL2}{NOTE}
%              produces the output for a \cite[NOTE]{FOO1,FOO2} command,
%              where entry FOOi is defined by \bibitem[LABELi]{FOOi}.
%              The switch @tempswa is true if the optional NOTE argument
%              is present.
%              The default definition is :
%                \@cite{LABELS}{NOTE} ==
%                   BEGIN [LABELS
%                         IF @tempswa = T THEN , NOTE FI
%                         ]
%                   END
%
%   \@biblabel : A macro to produce the label in the bibliography
%                entry.  For \bibitem[LABEL]{NAME}, the label is
%                generated by \@biblabel{LABEL}.  It has the default
%                definition \@biblabel{LABEL} -> [LABEL].
%  CONVENTION
%
%  \b@FOO : The name or number of the reference created by \cite{FOO}
%           E.g., if \cite{FOO} -> [17] , then \b@FOO -> 17.
%
% \end{oldcomments}
%
% \begin{macro}{\bibitem}
% \changes{v1.1g}{1995/05/08}{Removed unnecessary braces}
%    \begin{macrocode}
\def\bibitem{\@ifnextchar[\@lbibitem\@bibitem}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@lbibitem}
% \changes{LaTeX2.09}{1992/02/26}{Added \cs{hfill} to restore
%        left-alignment of bibliography labels in alpha style}
%    \begin{macrocode}
\def\@lbibitem[#1]#2{\item[\@biblabel{#1}\hfill]\if@filesw
      {\let\protect\noexpand
       \immediate
       \write\@auxout{\string\bibcite{#2}{#1}}}\fi\ignorespaces}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@bibitem}
% \changes{LaTeX2.09}{1991/11/13}{Changed counter enumi to enumiv,
%               as it says in the comment above}
% \changes{LaTeX2.09}{1992/01/10}{Changed \cs{c@enumiv} to \cs{value}
%       of \cs{@listctr}}
%    \begin{macrocode}
\def\@bibitem#1{\item\if@filesw \immediate\write\@auxout
       {\string\bibcite{#1}{\the\value{\@listctr}}}\fi\ignorespaces}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\bibcite}
% \changes{v1.1f}{1995/04/24}
%   {Make \cs{@onlypreamble} /1388.}
% \changes{v1.1h}{1995/06/19}
%   {Call \cs{@newl@bel} so repeated keys produce better warning.}
% \changes{v1.1i}{1995/07/14}
%   {Remove \cs{@onlypreamble} so still defined in new \cs{enddocument}}
%    \begin{macrocode}
\def\bibcite{\@newl@bel b}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\citation}
%    \begin{macrocode}
\let\citation\@gobble
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\cite}
% \changes{v1.1j}{1995/10/16}{(DPC) Make robust}
%    \begin{macrocode}
\DeclareRobustCommand\cite{%
  \@ifnextchar [{\@tempswatrue\@citex}{\@tempswafalse\@citex[]}}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\@citex}
% |\penalty\@m| added to definition of |\@citex| to allow a line
% break after the `,' in citations like [Jones80,Smith77]
% (Added 23 Oct 86)
%
% space added after the `,' (21 Nov 87)
%
% \changes{LaTeX2.09}{1991/10/25}
%      {added \cs{reset@font}, suggested by Bernd Raichle.}
% \changes{LaTeX2.09}{1991/11/06}
%     {added code to remove a leading blank}
% \changes{LaTeX2.09}{1992/08/14}
%      {added missing argument braces around \cs{hbox},
%               found by Ed Sznyter}
% \changes{LaTeX2.09}{1992/08/17}
%       {simplified code for removing leading blanks in
%               citation key (proposed by Frank Jensen and
%               Kresten Krab Thorup)}
% \changes{LaTeX2.09}{1993/08/06}
%  {Moved writing to .aux file in loop over citation keys
%               so that leading blanks are removed there as well.}
% \changes{v1.0c}{1994/05/05}{Set switch for warning and end of run.}
% \changes{v1.1e}{1995/04/24}
%   {Add \cs{mbox} to undefined case: latex/1239.}
% \changes{v1.1g}{1995/05/08}{Use \cs{@firstofone}}
% \changes{v1.1k}{1995/10/20}{Removed refundefined flag}
% \changes{v1.1l}{1995/12/07}{Restored name of \cs{G@refundefinedtrue}}
% \changes{v1.1m}{1997/04/24}{\cs{@empty} to avoid primitive
%    error on empty cite keys. latex/2432}
% \changes{v1.1n}{2002/12/13}{Added \cs{leavevmode} in case citation
%    is at start of paragraph (pr/3486)}
%    \begin{macrocode}
\def\@citex[#1]#2{\leavevmode
  \let\@citea\@empty
  \@cite{\@for\@citeb:=#2\do
    {\@citea\def\@citea{,\penalty\@m\ }%
     \edef\@citeb{\expandafter\@firstofone\@citeb\@empty}%
     \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
%    \end{macrocode}
%    Using |\hbox| instead of |\mbox| is fine because of the
%    |\leavevmode| above. In fact the use of a box around the citation
%    contents is more than questionable in my view (FMi), but within
%    2e I have to keep that for compatibility reasons as it would
%    probably change too many existing documents. Its main reason is
%    to avoid hyphenation of labels such as [FOOB89] into [FOO- B89]
%    so in certain styles it makes sense; but, for example, in author
%    year citations it becomes more than questionable.
%
%    So Chris added yet another hook here, as suggested by, at least,
%    Donald Arseneau.  Note that this one is inside the first argument
%    of the |\@cite| hook.
%    This decouples the top-level typesetting of the citation from
%    the details of the other business conducted here.  All this really
%    needs a complete rethink to get the right modularity.
%
% \changes{v1.1q}{2004/02/15}{Changed to use a hook with default
%     value \cs{hbox}}
%    \begin{macrocode}
     \@ifundefined{b@\@citeb}{\hbox{\reset@font\bfseries ?}%
       \G@refundefinedtrue
       \@latex@warning
         {Citation `\@citeb' on page \thepage \space undefined}}%
       {\@cite@ofmt{\csname b@\@citeb\endcsname}}}}{#1}}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\bibdata}
% \begin{macro}{\bibstyle}
%    \begin{macrocode}
\let\bibdata=\@gobble
\let\bibstyle=\@gobble
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
% \begin{macro}{\bibliography}
% \changes{LaTeX2e}{1994/01/18}
%         {Use \cs{@input@} so include files are listed.}
% \changes{LaTeX2e}{2018/11/09}
%         {Zap spaces in the argument as BibTeX doesn't support them (github/88)}
%    \begin{macrocode}
\def\bibliography#1{%
  \if@filesw
    \immediate\write\@auxout{\string\bibdata{\zap@space#1 \@empty}}%
  \fi
  \@input@{\jobname.bbl}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\bibliographystyle}
% \changes{v1.1d}{1994/12/09}{(DPC) Allow use in preamble.}
%    \begin{macrocode}
\def\bibliographystyle#1{%
  \ifx\@begindocumenthook\@undefined\else
    \expandafter\AtBeginDocument
  \fi
    {\if@filesw
       \immediate\write\@auxout{\string\bibstyle{#1}}%
     \fi}}
%    \end{macrocode}
% \end{macro}
%
%
%  \begin{macro}{\nocite}
%    (Added 14 Jun 85)
% \changes{v1.1c}{1994/11/10}{Fix \cs{nocite}\texttt{\char`\{*\char`\}}}
%
%    This puts information on the |.aux| file that causes
%    \BibTeX{} to include the citation list in the bibliography,
%    but puts nothing in the text.
%
% RmS 93/08/06: Made loop for |\nocite| like that for |\@citex|,
%               to get rid of leading spaces.
% \changes{v1.0b}{1994/05/03}{Make \cs{nocite} issue a warning
%            for an undefined citation key.}
% \changes{v1.0c}{1994/05/05}{Do not write page number in
%            \cs{nocite} warning message.}
% \changes{v1.0c}{1994/05/05}{Set switch for warning and end of run.}
% \changes{v1.1g}{1995/05/08}{Use \cs{@firstofone}}
% \changes{v1.1k}{1995/10/20}{Removed refundefined flag}
%    \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2021/05/01}%
%<latexrelease>                 {\nocite}{Allow nocite in preamble}%
\def\nocite#1{\@bsphack
%    \end{macrocode}
%    With the implementation designed already in \LaTeX\,2.09 the
%    |\nocite| command will not work before |\begin{document}| since
%    it tries to write to the |.aux| file which is not open before
%    that point. As a result the ``reference'' will appear on the
%    terminal and nothing else will happen.
%
%    [This would be easy to fix, but then a document using the fix will
%    silently fail on an older release of \LaTeX{}, missing all
%    citations done with |\nocite|. Thus we do only generate an error
%    message and leave the fix for a \LaTeXe{} successor.]
%  
%    Given that we are now a quarter century into using \LaTeXe{}
%    there is no good reason any more do limit ourself to 2.09
%    conciderations. So we now simply delay the \cs{nocide} if it is
%    issued in the preamble.
%
% \changes{v1.1o}{2003/05/18}{Check if we are after \cs{document}}
% \changes{v1.1p}{2004/01/04}{Changed error message}
%    \begin{macrocode}
  \ifx\@onlypreamble\document
%    \end{macrocode}
%    Since we are after |\begin{document}| we can do the citations:
%    \begin{macrocode}
    \@for\@citeb:=#1\do{%
      \edef\@citeb{\expandafter\@firstofone\@citeb}%
      \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
      \@ifundefined{b@\@citeb}{\G@refundefinedtrue
          \@latex@warning{Citation `\@citeb' undefined}}{}}%
  \else
%    \end{macrocode}
%    But before |\begin{document}| we raised an error message in the
%    past but as of 2021/05 not any longer.
%    \begin{macrocode}
%    \@latex@error{Cannot be used in preamble}\@eha
%    \end{macrocode}
%    Instead we delay the declaration to the start of the document.
%    We have to use a late hook for this, so that it comes after the
%    \texttt{.aux} file is open for writing and after
%    \cs{@preamblecmds} was executed to change the above
%    test. Therefore \cs{AtBeginDocument} would still be too early.
% \changes{v1.1s}{2020/12/10}{Delay any \cs{nocite} in the preamble
%    instead of raising an error}
%    \begin{macrocode}
    \AddToHook{begindocument/end}[kernel]{\nocite{#1}}%
  \fi
  \@esphack}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%    \end{macrocode}
%
%    \begin{macrocode}
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease>                 {\nocite}{Allow nocite in preamble}%
%<latexrelease>
%<latexrelease>\def\nocite#1{\@bsphack
%<latexrelease>  \ifx\@onlypreamble\document
%<latexrelease>    \@for\@citeb:=#1\do{%
%<latexrelease>      \edef\@citeb{\expandafter\@firstofone\@citeb}%
%<latexrelease>      \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
%<latexrelease>      \@ifundefined{b@\@citeb}{\G@refundefinedtrue
%<latexrelease>          \@latex@warning{Citation `\@citeb' undefined}}{}}%
%<latexrelease>  \else
%<latexrelease>    \@latex@error{Cannot be used in preamble}\@eha
%<latexrelease>  \fi
%<latexrelease>  \@esphack}
%<latexrelease>
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
%    \end{macrocode}
%
%    Since |\nocite{*}| should not produce a warning about undefined
%    citation keys (see PR 557), we need to set the control sequence
%    `|\b@*|' to something other than |\relax|. As a result |\cite{*}|
%    will not warn either (but that never worked with \BibTeX{} in the
%    first place).
%    \begin{macrocode}
\expandafter\let\csname b@*\endcsname\@empty
%    \end{macrocode}
%  \end{macro}
%
%
% \subsection{Default definitions}
%
%    This hook determines the `relative formatting' of the two logical
%    parts of a citation with comment.
% \begin{macro}{\@cite}
%    \begin{macrocode}
\def\@cite#1#2{[{#1\if@tempswa , #2\fi}]}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\@cite@ofmt}
% \changes{v1.1q}{2004/02/15}{Added hook with default value \cs{hbox}}
%    This is, in general, a command that appears to have one argument
%    whose value is, in the kernel, a single cs whose name is the
%    expansion of |b@\@citeb|; the expansion of this cs will
%    typically be some hmode material that produces the detailed
%    typeset form of just the citations themselves.
%    \begin{macrocode}
\let\@cite@ofmt\hbox
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\@biblabel}
% \changes{LaTeX2.09}{1992/01/14}{removed \cs{hfill}}
%    \begin{macrocode}
\def\@biblabel#1{[#1]}
%</2ekernel>
%    \end{macrocode}
%  \end{macro}
%
% \Finale
%