path: root/macros/latex/base/ltbibl.dtx

% \iffalse meta-comment
%
% Copyright (C) 1993-2022
% 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
%