%% ttb_en.sec1.tex
%% Copyright 2003-2005  Nicolas Markey
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2003/12/01 or later.
%
% This work has the LPPL maintenance status "maintained".
% The Current Maintainer of this work is Nicolas Markey
%
% This work consists of the files
%       ttb_en.tex
%       ttb_en.sec1.tex  ttb_en.sec2.tex  ttb_en.sec3.tex
%       ttb_en.sec4.tex  ttb_en.sec5.tex  ttb_style.sty
%       local.bib        idxstyle.ist     Makefile
% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf

\mypart{Basic bibliography with \LaTeX}\label{part1}
\parttoc
\mtcskip

\bt is often seen as something magical, as well as \LaTeX
bibliography-related commands in general. Many users simply copy and paste
classical examples without trying to understand how it works. But in
fact, a bibliography in \LaTeX is nothing but a \emph{list} of
\emph{references} mentioned in a document. If we had to do it ``by
hand'', 
without knowing anything about the \env{thebibliography} environment,
it could look like this:

\medskip
\begin{verbatim}
This is the main matter of the document, mentioning 
[\ref{doc1}] and [\ref{doc2}], for instance.
\section*{References}
\begin{enumerate}
  \renewcommand\labelenumi{[\theenumi]}  %% numbers are surronded with brackets
  \item \label{doc1} Michel Goossens, Franck Mittelbach and Alexander
        Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993.
  \item \label{doc2} Leslie Lamport, \emph{\LaTeX: A Document Preparation
        System}, Addison Wesley, 1997.
\end{enumerate}
\end{verbatim}
\noindent which, when compiled, gives
\begin{myex}
This is the main matter of the document, mentioning 
[\ref{doc1}] and [\ref{doc2}], for instance.
\section*{References}
\begin{enumerate}
  \renewcommand\labelenumi{[\theenumi]}  %% numbers are between brackets
  \item \label{doc1} Michel Goossens, Franck Mittelbach and Alexander
        Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993.
  \item \label{doc2} Leslie Lamport, \emph{\LaTeX: A Document Preparation
        System}, Addison Wesley, 1997.
\end{enumerate}
\end{myex}

This is mostly what the \env{thebibliography} environment does (it
starts a \env{list} environment, similar to~\env{enumerate}), 
\cmd{bibitem} corresponding
to the \cmd{item} commands. One major difference is that \cmd{bibitem} 
allows for more general cross-references than \cmd{item} and
\cmd{label} (for example, one can cite~\cite{latex:lc}).


This is what this part deals with: ``Writing a bibliography
\emph{without} \bt''.  This is not the main goal of this manual, but 
it is a cornerstone for understanding the sequel.


\mysection{The \nienv{thebibliography} environment}


%%
%% Fin trad.
%%

The \env{thebibliography} environment is not defined in \LaTeX
itself (neither is it in \TeX\footnote{\bt may be used with plain \TeX,
you'll simply have to input the \sty[tex]{btxmac} package}, of course). It has
to be defined by the  
class file used in the document (\emph{e.g.} \cls{article} or
\cls{book}). As mentioned earlier, it is a \env{list}-like
environment inside a new \cmd{section} (or \cmd{chapter}, depending on
the document class\footnote{This is the reason why \env{thebibliography}
has to be defined in the class files. The
other bibliographic commands are defined in the standard \LaTeX format.}). 
This list has to be set up carefully, however, in order to avoid indentation
problems. For instance, if we put ``alphanumerical'' labels in the previous
example, we would get:
\begin{myex}
\section*{References}
\begin{enumerate}
\renewcommand\labelenumi{[\theenumi]}
\item[{[GMS93]}] Michel Goossens, Franck Mittelbach, and Alexander
Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993.
\item[{[Lam97]}] Leslie Lamport, \emph{\LaTeX: A Document Preparation
System}, Addison Wesley, 1997.
\end{enumerate}
\end{myex}

In order to avoid this problem, \env{thebibliography} has a mandatory
argument, which should be the largest label occurring in the list. This will
allow to set up margins properly.

\medskip
Let's now have a look at the precise definition of the
\env{thebibliography} environment (as defined in the \cls{article}
class, for instance):
\begin{listing}{1}
\newenvironment{thebibliography}[1]
     {\section*{\refname
        \@mkboth{\MakeUppercase\refname}{\MakeUppercase\refname}}%
\end{listing}
As mentioned earlier, \env{thebibliography} starts a new
section\footnote{It is in fact a \cmd{section*}, so that it won't
  appear in the table of contents. In order to cleanly insert the
  bibliography in your table of contents, use the \sty{tocbibind}
  package. Other methods you can think of will probably lead to wrong
  page numbers.}. The environment also sets the page headers\footnote{The
  standard  
  \sty{apalike} package hard-codes the headers to ``REFERENCES'' or
  ``BIBLIOGRAPHY'', depending on the class file. 
  But another package (with the same name, unfortunately) correctly sets
  the headers to \cmd{refname} or \cmd{bibname}. Simply check in the sources if you have
  problems for redefining the headers with that package.}.

\begin{listingcont}
      \list{\@biblabel{\@arabic\c@enumiv}}%
           {\settowidth\labelwidth{\@biblabel{#1}}%
\end{listingcont}
This is not surprising either: We start a new \env{list}
environment\footnote{The \cmd{list} command is equivalent to a
  \texttt{\bs begin\{list\}}, and has to be followed with a
  \cmd{endlist}.}. It takes two mandatory arguments: 
\begin{itemize}
\item the first one (\texttt{\bs\at biblabel\{...\}}) defines the format of
the default command for 
  generating labels. Here it is defined with the \verb+enumiv+
  counter, using \cmdat{biblabel}{}\footnote{\cmdat{biblabel} is
  defined in \LaTeX. It outputs its argument surrounded with
  brackets. The precise definition is:
\texttt{\bs def\bs\at biblabel\#1\{[\#1]\}}.}. 
 Thus we have [1], [2], ... Since \cmd{bibitem} is a sort of
  \cmd{item}, it may have an optional argument for modifying this
  default label. 
\item The second argument(lines~5 above to~11 below) is a set of commands that
  are run at  the 
  beginning of the environment. They set the values
  of different lengths and parameters of the \env{list} environment.
  This is where we need the longest label (which the mandatory
  argument of the \env{thebibliography} environment should be set to),
  in order to correctly  indent the whole list.
  People often write \verb+\begin{thebibliography}{99}+, but this is
  correct only if there are between $10$ and $99$ cited references
  (assuming all digits have the same length, which is the case with
  the   \textsf{cmr} fonts). 
\end{itemize}


The rest of the definition of \env{thebibliography} contains some 
borderline definitions for the list environment and the use of the
\verb+enumiv+ counter:
\begin{listingcont}
            \leftmargin\labelwidth
            \advance\leftmargin\labelsep
            \@openbib@code
            \usecounter{enumiv}%
            \let\p@enumiv\@empty
            \renewcommand\theenumiv{\@arabic\c@enumiv}}%
\end{listingcont}
\cmdat{openbib\at code}, which is empty by default, allows 
to modify some parameters if necessary. Option \texttt{openbib} of
classical style files uses this command for resetting some parameters.
Line~9 to~11 set the list counter.

Last, within the reference list, spacing rules as well as some special
penalties are used: 
\begin{listingcont}
      \sloppy
      \clubpenalty4000
      \@clubpenalty \clubpenalty
      \widowpenalty4000%
      \sfcode`\.\@m}
\end{listingcont}


That's it for the initialization of this environment. Ending the
\env{thebibliography} is much easier:
we just echo a warning if no reference has been included, and we close
the \env{list} environment:
\begin{listingcont}
     {\def\@noitemerr
       {\@latex@warning{Empty `thebibliography' environment}}%
      \endlist}
\end{listingcont}



\mysection{The \protect\nicmd{bibitem} command}\label{bibitem}

Inside the \env{list} environment described above, we have to insert
\cmd{item}{}s, as is usual. It will be a special \cmd{item}, though, in
order to have a correct rendering of each bibliographical item. The
adequate command is named \cmd{bibitem}, and has two roles: Writing
the new entry in the list, and defining the cross-reference to be used
when citing this entry, which defaults to 
\verb+\@biblabel{\@arabic\c@enumiv}+. The result is [1] for instance,
but of course can be modified into [GMS94], say, 
with an optional argument,
exactly in the same way as for an \cmd{item}.
Here is the precise definition of \cmd{bibitem}:
\begin{listing}{1}
\def\bibitem{\@ifnextchar[\@lbibitem\@bibitem}
\end{listing}
\cmd{bibitem} calls \cmdat{lbibitem} if
there is an optional argument, and \cmdat{bibitem} otherwise.
Those auxiliary commands are defined as follows:
%
\begin{listing}{1}
\def\@lbibitem[#1]#2{\item[\@biblabel{#1}\hfill]\if@filesw
      {\let\protect\noexpand
       \immediate
       \write\@auxout{\string\bibcite{#2}{#1}}}\fi\ignorespaces}
\end{listing}
%
Let's take an example in order to see how it works: Assume we wrote 
\verb+\bibitem[GMS94]{companion}+.
The command first creates an item having the same optional argument,
which will be surrounded with brackets by \cmdat{biblabel} and flushed
to the left by \cmd{hfill}.\label{biblabel}
It then write a \cmd{bibcite} command, with two arguments, into the
\ext{aux} file\footnote{More precisely, the file pointed to by
the \cmdat{auxout} command, but this generally is the \ext{aux}
file.}.  
\cmd{bibcite} is simply defined as follows:
\label{bibcite}
\begin{listing}{1}
\def\bibcite{\@newl@bel b}
\end{listing}

The \cmdat{newl\at bel} command requires three arguments, \texttt{\#1},
 \texttt{\#2} and \texttt{\#3}, and defines a command named
 \texttt{\#1\at\#2} (with of course \texttt{\#1} and \texttt{\#2} being
 replaced by their values) whose value is the third argument \texttt{\#3}.

This behavior is the same as when defining a cross reference (with
\cmd{label}) in the document: when the \ext{aux} file is read by
\LaTeX (namely at the \verb+\begin{document}+ and
\verb+\end{document}+), those \cmdat{newl\at bel} commands are 
executed, and a \verb+\b@companion+ command is defined, containing,
in our case, \texttt{GMS93}. 

When there is no optional argument, it is quite similar:
%
\begin{listing}{1}
\def\@bibitem#1{\item\if@filesw \immediate\write\@auxout
       {\string\bibcite{#1}{\the\value{\@listctr}}}\fi\ignorespaces}
\end{listing}
%
The new \cmd{item} is created, and the \cmd{bibcite} command is 
output in the \ext{aux} file. The only new thing to know here is that
\cmdat{listctr} is the list counter, and points to \verb+enumiv+ as requested
by the \cmd{usecounter} command in the definition of \env{thebibliography}.
Everything after the \cmd{bibitem} (and its argument(s)) is
output  in the document, within the recently created item of the
list, until the next \cmd{bibitem} or the end of the
\env{thebibliography} environment\footnote{Some packages redefine
  \cmd{bibitem} and could not meet this last rule. See
  section~\ref{redefbibitem} on this topic.}.

\medskip
To conclude, here is a small example of a bibliography, having two
entries, as it could be defined in a document:

\begin{verbatim}
\begin{thebibliography}{GMS93}   %% GMS93 is the longest label.
\bibitem[GMS93]{companion} Michel Goossens, Franck Mittelbach and Alexander
     Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993.
\bibitem[Lam97]{lamport} Leslie Lamport, \emph{\LaTeX: A Document Preparation
     System}, Addison Wesley, 1997.
\end{thebibliography}
\end{verbatim}
And here is the result:

\begin{myex}
\begin{thebibliography}{GMS93}
\bibitem[GMS93]{companion1} Michel Goossens, Franck Mittelbach and Alexander
     Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993.
\bibitem[Lam97]{lamport1} Leslie Lamport, \emph{\LaTeX: A Document Preparation
     System}, Addison Wesley, 1997.
\end{thebibliography}
\end{myex}


\mysection{The \protect\nicmd{cite} command}\label{cite}

When considering a bibliography as a list of cross-references,
\cmd{cite} is the equivalent for \cmd{ref}. It has one mandatory
argument, which is the internal label to be cited. It also has an
optional argument, that can be used to add some comments to the
reference. For instance, a good reference concerning \bt is
\cite[Chap.~13]{latex:lc}, which is obtained by entering 
\verb+\cite[Chap.~13]{companion}+.\label{citeopt}


Here is how it is defined\footnote{Details about
  \cmd{DeclareRobustCommand} are given at page~\pageref{DRC}. If you
  don't know what it is, you can see it as a simple
  \cmd{newcommand}.}: 
%
\begin{listing}{1}
\DeclareRobustCommand\cite{%
  \@ifnextchar [{\@tempswatrue\@citex}{\@tempswafalse\@citex[]}}
\end{listing}
% 
If there is an optional argument, the boolean variable \cmdat{tempswa}
is set to true (we need to remember that an optional argument was provided), 
and  \cmdat{citex} is called. Otherwise, \cmdat{tempswa} is false, and
\cmdat{citex} is called with an empty optional argument.


Before explaining \cmdat{citex}, we first have a quick look at
\cmdat{cite}, which will be used by \cmdat{citex}. This will help 
understand how \cmdat{tempswa} is used: 
%
\begin{listing}{1}
\def\@cite#1#2{[{#1\if@tempswa , #2\fi}]}
\end{listing}
This is the command used for outputting the reference in the
document. The second argument is used only if \cmdat{tempswa} has been
set to true. Together with the first argument, they are put into
brackets, and output in the document.

Now \cmdat{citex}~will be the ``bridge'' between \cmd{cite} and \cmdat{cite}:
\label{citex}
%
\begin{listing}{1}
\def\@citex[#1]#2{%
  \let\@citea\@empty
  \@cite{\@for\@citeb:=#2\do
\end{listing}

This calls \cmdat{cite}. Its first argument will be computed by the
\cmdat{for} command, in case several references are cited at one
time.\index{latex}{citea@\texttt{\protect\bs\protect\at citea}}
%
\begin{listingcont}
    {\@citea\def\@citea{,\penalty\@m\ }%
\end{listingcont}
%
Starting from the second run through the \cmdat{for}-loop, we add a
comma, and a penalty for a line break not to occur between references.
The default is to never have a line break inside a set of references.
%
\begin{listingcont}
     \edef\@citeb{\expandafter\@firstofone\@citeb\@empty}%
\end{listingcont}
%
This redefines \cmdat{citeb}, the variable used in the loop. The
\cmdat{for} command successively sets \cmdat{citeb} to all the values
that have been cited, and \cmdat{citeb} is redefined here in order to
remove extra spaces. This is somewhat tricky, but it works.
\label{citation}

\begin{listingcont}
     \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
\end{listingcont}
%
This writes a \cmd{citation} command in the \ext{aux} file, indicating
that \cmdat{citeb} has been cited in the document. This is not useful
here, but will be crucial for \bt to generate the bibliography (see
section~\ref{bibtex}).

\begin{listingcont}
     \@ifundefined{b@\@citeb}{\mbox{\reset@font\bfseries ?}%
       \G@refundefinedtrue
       \@latex@warning
         {Citation `\@citeb' on page \thepage \space undefined}}%
\end{listingcont}
%
This handles cases where the requested reference does not exist yet. In
that case, the reference is replaced by a boldface question mark. A
warning is also echoed in the \ext{log} file.

\begin{listingcont}
       {\@cite@ofmt{\csname b@\@citeb\endcsname}}}}{#1}}
\end{listingcont}
If the reference exists, it is written here, using the 
\nicmd{b\at...} command created when reading the \ext{aux} file (\cf
page~\pageref{bibcite}). 
\cmdat{cite\protect\at ofmt} is equivalent to~\cmd{hbox}\footnote{The
command~\cmdat{citex} is defined with \cmd{hbox} in old (before 2003) versions
of \LaTeX.}.
The loop is executed for all the requested
references, and the whole result is then passed to \cmdat{cite},
together with the optional second argument, which is \verb+#1+ here. 

\medskip
This may look intricate, but it is really easy to use: You simply 
enter \verb+\cite{companion, lamport}+ in order to get \cite{latex:lc,
  latex:dps}, with the bibliographic items shown at the end of the previous
  section. 



\mysection{Some more little tricks}\label{truc1}

\mysubsection{What is \protect\nicmd{DeclareRobustCommand}?}
\label{DRC}

A command having an optional argument, such as \cmd{cite}, is said to
be \emph{fragile}: Generally speaking, they cannot be directly used
in the argument of other commands (for instance, \cmd{cite} in the
argument of a \cmd{section}). These problems can be overcome by preceding
the fragile command by a \cmd{protect}, but this is annoying. The
other solution is to declare the command as robust, by defining it
with \cmd{DeclareRobustCommand} instead of \cmd{newcommand}.


\mysubsection{Changing the name of the bibliography}

This is obvious from the definition of the \env{thebibliography}
environment: We simply have to redefine \cmd{refname}, which defaults
to \emph{\refname}. However, this
only works with the \cls{report} class. The \cls{book} and
\cls{article} classes use \cmd{bibname} instead, which defaults to
\emph{\bibname}. 

For instance, when using \cls{report}, you'll write:
\begin{verbatim}
   \renewcommand{\refname}{Some references}
\end{verbatim}
while with \cls{book} or \cls{article}, it should be:
\begin{verbatim}
   \renewcommand{\bibname}{Some references}
\end{verbatim}
As mentioned earlier, \sty{apalike} does not use \cmd{refname} and hard-codes
the reference name in the page headers.

\mysubsection{Adding text before the first reference}

Putting text just after the beginning of the \env{thebibliography}
environment raises an error, since the \env{list} environment demands
an \cmd{item} command. Thus we will put a real \cmd{item}, then add
some negative horizontal space back to the left margin, and write our
text within a \env{minipage} environment (in order to avoid
indentation due to the list):

\begin{verbatim}
\begin{thebibliography}{GMS93}
\item[]
\hskip-\leftmargin
\begin{minipage}{\textwidth}
Here are some useful references about \LaTeX. They are
available in every worthy bookshop. Many other good documentations
might be found on the web (the FAQ of \textsf{comp.text.tex} for
instance). 
\end{minipage}
\bigskip
\bibitem[GMS93]{companion} Michel Goossens, Franck Mittelbach and
     Alexander 
     Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993.
\bibitem[Lam97]{lamport} Leslie Lamport, \emph{\LaTeX: A Document Preparation
     System}, Addison Wesley, 1997.
\end{thebibliography}
\end{verbatim}
This code gives:

\begin{myex}
\begin{thebibliography}{AAA00}
\item[]
\hskip-\leftmargin
\begin{minipage}{\textwidth}
Here are some useful references about \LaTeX. They are
available in every worthy bookshop. Many other good documentations
might be found on the web (the FAQ of \textsf{comp.text.tex} for
instance). 
\end{minipage}

\bigskip
\bibitem[GMS93]{companion2} Michel Goossens, Franck Mittelbach and
     Alexander 
     Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993.
\bibitem[Lam97]{lamport2} Leslie Lamport, \emph{\LaTeX: A Document Preparation
     System}, Addison Wesley, 1997.
\end{thebibliography}
\end{myex}


\mysubsection{Redefining \protect\nicmd{bibitem}}\label{redefbibitem}


Some style files need redefining the \cmd{bibitem} command, or in 
fact \cmdat{bibitem} and \cmdat{lbibitem}, so that an entry has to 
end with a \cmd{par} command (or an empty line). \sty{backref} is an
example of such a style file. Some other will turn the optional
argument of \cmd{bibitem} into a mandatory one. \sty{apalike} does
so. 

I've nothing to add about that, but it is useful to know this to 
avoid spending too much time on debugging...



\mysubsection{Turning brackets into parentheses}


As we saw earlier, \cmd{biblabel} is in charge of adding brackets
around reference labels, in the reference list. It is easy 
to redefine it in order to get parentheses: 

\begin{verbatim}
\makeatletter		% @ is now a letter
\def\bibleftdelim{(}
\def\bibrightdelim{)}
\def\@biblabel#1{\bibleftdelim #1\bibrightdelim}
\makeatother		% @ is a symbol
\end{verbatim}

This does the trick, and it is now easy to change parentheses into
anything else, by redefining \nicmd{bibleftdelim} and
\nicmd{bibrightdelim}. 

However, this won't change the behavior of \cmdat{cite}, which will
still write brackets around cited reference labels. Thus we also have
to redefine \cmdat{cite}:
\begin{verbatim}
\makeatletter
\def\@cite#1#2{\bibleftdelim{#1\if@tempswatrue , #2\fi}\bibrightdelim}
\makeatother
\end{verbatim}

\mysubsection{... and more}

Several packages have been written for modifying the look 
of bibliographies and citations. For instance, 
the package \sty{cite} allows to modify the result of the 
\cmd{cite} command: turning brackets into parentheses, but also
sorting and compressing a set of numeric references. 
The package \sty{overcite} allows, moreover, to get references 
displayed as superscript.

The package \sty{splitbib} changes the output of the list of 
references: it allows to split the bibliography into several 
categories, and\slash or reordering that list. See the 
documentation~\cite{splitbib} for more details.

\mysubsection{Can the symbol \$ be used in an internal key?}

Probably not, but I don't know exactly which character may or may not
be used. Obviously, any letter and digit can be used, and my opinion
is that it is quite enough. On the other hand, commas, curly brackets
and backslashes are clearly forbidden. For the other ones, I don't
know, just give it a try and you'll know. 


\mysection*{Conclusion}

Well... It could be over right now, since we know how to write a
bibliography. However, typesetting all references by hand is long and
annoying. Moreover, when writing several articles on related areas, 
we often cite the same sets of references, but possibly with different styles. 
It would be interesting to have a \emph{database} containing a large
set of references, some of which would be picked up, formatted and typeset by
\LaTeX. This does exist, and is described in the sequel.
