ltbibl.dtx
% \iffalse meta-comment
%
% Copyright (C) 1993-2024
% The LaTeX 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}
[2022/03/10 v1.1t 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.
%
% \MaybeStop{}
%
%
% \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}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\cite}{check for blank}%
\DeclareRobustCommand\cite{%
\@ifnextchar [{\@tempswatrue\@citex@checkblank}{\@tempswafalse\@citex@checkblank[]}}
% \end{macrocode}
% Due to the way \cs{@for} as used in \cs{@citex} behaves an empty
% argument to \cs{cite} did not produce any warning for a missing
% citation. So we now inject a command before calling \cs{@citex} that
% does the checking for us. It is not done in \cs{@citex} directly,
% because that command is altered by a number of packages/classes
% and this way it is more likely that the check survives.
% \changes{v1.1t}{2022/03/10}{Ensure that an empty argument generates
% a warning (gh/790)}
% \begin{macrocode}
\def\@citex@checkblank[#1]#2{%
\IfBlankTF {#2}%
{\@citex[#1]{\space}}%
{\@citex[#1]{#2}}%
}
%</2ekernel|latexrelease>
% \end{macrocode}
%
% \begin{macrocode}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease> {\cite}{check for blank}%
%<latexrelease>
%<latexrelease>\DeclareRobustCommand\cite{%
%<latexrelease> \@ifnextchar [{\@tempswatrue\@citex}{\@tempswafalse\@citex[]}}
%<latexrelease>\let\@citex@checkblank\@undefined
%<latexrelease>
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
% \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/06/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
%
