\chapter{Bibliographic references}\label{sec:bib}

For bibliographic references, \LaTeX{} uses the \BT{} database
system. This chapter, which is not part of the actual introduction,
takes a look at:
\begin{itemize}
\item incorporating bibliographic references during the
  compilation process, see section~\ref{sec:running}.
\item the evolution of citation- and bibliography handling, see
  section~\ref{sec:generations}.
\item the \BT{} database format, and software to build and maintain
  such a database, see sections~\ref{sec:database} and
  \ref{sec:make_entries}.
\end{itemize}

\BT{} practice files are in a separate subdirectory \path{bibtex} of
the practice zipfile.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The why and how of \BT{}}\label{sec:bibworks}

Different journals have different requirements for bibliographic
references:
\begin{itemize}
  \item What to include, in what order
  \item Capitalization
  \item Punctuation
  \item Abbreviations
  \item Styling of text
\end{itemize}
With a bibliography manager you can maintain a database of
bibliographic references and have it generate the references for
any paper in the required format.

Below a very short \LaTeX{} source which references entries from an
existing \BT{} database (you can find the full \BT{} entries on page
\pageref{verb:first_bib_example}):%\enlargethispage*{28pt}

\begin{verbatim}
\documentclass{article}
\bibliographystyle{plain}
\begin{document}

See \cite{lcompanion} and \cite{biboostrum}.

\bibliography{bibdemo} % this line specifies bibdemo.bib as database
\end{document}
\end{verbatim}

\nextblock
As you can guess, \texttt{lcompanion} and \texttt{biboostrum} are
keys of database entries:%\enlargethispage*{-10bp}
\begin{verbatim}
@Article{biboostrum,
  author = "Piet van Oostrum",
  title = "Een tutorial over het gebruik van {Bib{\TeX}}",
  year = 2004,
  ...
}
@Book{lcompanion,
  Author = "Frank Mittelbach and Michel Goossens",
  Title = "The {\LaTeX{}} Companion",
  year = 2004,
  ...
}
\end{verbatim}
We get the following output:

\includedetail[.8]{../bibsamples/bibdemo1}

\nextblock
You can put the \cmd{bibliographystyle} command anywhere before the
\cmd{bibliography} command.\footnote{\LaTeX{} used to be more
  restrictive in this respect. Therefore, many old-time \LaTeX{}
  users still place the \cmd{bibliographystyle} command right before
  the \cmd{bibliography} command.}

Bibliography styles are provided by \texttt{.bst} files:
\texttt{plain.bst} in the example above, \texttt{alpha.bst} in the
example from section~\ref{sec:original}; both hidden deep inside
the \TL{} directory structure.

Once you have prepared your \LaTeX{} source and your \BT{} database,
compilation requires the following steps:\label{page:bibrun}
\begin{enumerate}
\item Run \texttt{pdflatex} to generate the information that \BT{} needs
\item Run \texttt{bibtex} to generate the list of references
\item Run \texttt{pdflatex} to include the generated list of references
\item Run \texttt{pdflatex} again to resolve bibliographic references
  (just like other cross-references)
\end{enumerate}
The \TS{} Build command (\button{button_build}) handles all this for
you.

After further editing a single \texttt{pdflatex} run should be
enough as long as the list of references stays the same.

\section{nocite: entries without citations}\label{nocite}

You can use \cmd{nocite} instead of \cmd{cite} if you do not want an
automatically generated citation in the running text but do want an
entry in the list of references:
\begin{verbatim}
\nocite{lcompanion}
\end{verbatim}

\subsubsection{Tip}
You can quickly create a formatted printout of your
\BT{} database with the \verb+\nocite{*}+ command (see
\texttt{testbib.tex} from the practice files):
\begin{verbatim}
\documentclass{article}
\bibliographystyle{plain}
\begin{document}
\nocite{*}
\bibliography{your_bibtex_file}
\end{document}
\end{verbatim}

\subsection{Practice}\label{sec:running}

\begin{enumerate}
\item Run the \path{bibtex_sample} example. Check how the \cmd{cite}
  commands in the \LaTeX{} source, the
  entries in the \BT{} database and the citations and reference
  entries in the typeset output match up with each other.

\item Collect a few fragments with bibliographic references from
  \url{http://en.wikipedia.org/wiki/Factors_of_production}
  into a \LaTeX{} document, replacing footnotes with proper cite
  commands and a proper list of references. You can use the
  \texttt{factors.bib} bibliography database from the practice files.
\end{enumerate}

\section{Bibliography styles: three
  generations}\label{sec:generations}

\subsection{The original \BT{}}\label{sec:original}

The original \BT{} from 1988 uses a simple citation style: the
entries in the list of references get an automatically generated
label -- either numerical or alphanumerical -- for
cross-referencing. We already saw numerical references. Here is an
example with alphanumerical labels:

\begin{verbatim}
\documentclass{article}
\bibliographystyle{alpha}
\begin{document}

See \cite{lcompanion} and \cite{biboostrum}.

\bibliography{bibdemo}
\end{document}
\end{verbatim}

\includedetail[.8]{../bibsamples/bibdemo2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The next step: author -- Year citation
  styles}\label{sec:natbib}

The classical bibliography styles didn't provide for author -- year
citation styles, such as in the examples below:

\includedetail[.8]{../bibsamples/bibst_chic}

\nextblock
or, with a different bibliography style:

\includedetail[.8]{../bibsamples/bibst_arev}

\nextblock
Note the absence of labels in the list of references.

Author-year citation styles are provided by the \texttt{natbib}
package and by various alternatives such as the \texttt{apalike} and
\texttt{harvard} packages. \texttt{natbib} is the most popular one
and can replace most of the others. This is the \LaTeX{} preamble
code:
\begin{verbatim}
\usepackage{natbib}
\bibliographystyle{chicago} % first example
%\bibliographystyle{apsrev} % second example
\end{verbatim}
Cite commands in the running text:%\enlargethispage*{13pt}
\begin{verbatim}
See \citeauthor{castaldo2006} from \citeyear{castaldo2006} and
\cite{texbook}.
\end{verbatim}

\nextblock
A sample of citation commands supported by \texttt{natbib}:

\begin{tabular}{@{}lll@{}}
\cmd{cite\{tamethebeast\}} & \cite{tamethebeast} \\
\cmd{citet\{tamethebeast\}} & \citet{tamethebeast} & `in-\textbf{t}ext' \\
\cmd{citep\{tamethebeast\}} & \citep{tamethebeast} &
 `\textbf{p}arenthesized' \\
\cmd{citet[noted] \{lshort\}} &
  \multicolumn{2}{l}{\citet[noted]{lshort}} \\
\cmd{citep*\{lshort\}} &
  \multicolumn{2}{l}{\citep*{lshort}} \\
\cmd{citeauthor\{tamethebeast\}} & \citeauthor{tamethebeast} \\
\cmd{citeyear\{lshort\}} & \citeyear{lshort}
\end{tabular}

\nextblock
\cmd{nocite} works as usual.

See the natbib manual for more variations and for customization
options.

The practice files include a file \path{bibtex_natbib_sample.tex} to
get you started.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Generating your own bibliography style with
  custom-bib/makebst}\label{sec:makebst}

Journals sometimes have very specific requirements as to the
formatting of bibliographic entries, without providing a
bibliography style implementing this formatting. Even if a suitable
style exists, it may be hard to find one, although the
\citetitle{faq} has to offer some advice.  One way out is creating
your own \texttt{.bst} file.

If a style is almost correct, \emph{and} if you can make some sense
out of \texttt{.bst} files (a big if!), then maybe you can fix it
yourself.

Another option is the \texttt{makebst} program. This is a two-step
process. In the first step, you have to answer a very long list of
questions. Your answers are written to an intermediate answers file,
which you can edit afterwards if some answers turned out not to be
quite right. In the second step, a \texttt{.bst} file is generated
from this list of answers. Search the documentation list (see
\ref{sec:doclist}) for \emph{custom-bib} or \emph{makebst}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The latest and greatest: biblatex}\label{sec:do_biblatex}

A radical reimplementation of bibliography support is
biblatex\nocite{biblatex}. Bibliography styles aren't written in the
unfamiliar .bst syntax but in \LaTeX{}, and the role of \BT{} is
reduced to collecting and sorting the bibliographic entries. \LaTeX{}
itself selects, arranges and formats the fields of the
bibliographic entries.
Advantages include:
\begin{itemize}
\item many variations in bibliography style can be realized simply with
  package options, without editing \path{.bst} files
\item better support for non-Western languages
\item more citation options, because \LaTeX{} has access to all the
  bibliographic information
\item easy per-chapter bibliographies
\end{itemize}
Fortunately, an old \BT{} database is still compatible with
biblatex.

\subsection*{Getting started with biblatex}

You can easily experiment with biblatex. If you include a package
option \texttt{natbib} or \texttt{natbib=\dbr{}true} then you
can keep using natbib cite commands in your \LaTeX{} source.

You should also configure \TS{} to use biber instead of \BT{}
(\menupath{Options / Configure TeX\dbr{}studio / Build / Default
  Bibliography Tool}).

Below are biblatex preamble commands, assuming biber as
backend; note that with biblatex the \cmd{bibliography} command
should be in the preamble:
\begin{verbatim}
\usepackage[style=numeric]{biblatex}
\bibliography{bibdemo}
\end{verbatim}
And near the end:
\begin{verbatim}
\printbibliography
\end{verbatim}
The complete source for the first example:
\begin{verbatim}
\documentclass{article}
\usepackage[style=numeric]{biblatex}
\bibliography{bibdemo}
\begin{document}
See \cite{lcompanion} and \cite{bacgri2003}.

\printbibliography
\end{document}
\end{verbatim}
Output:

\nextblock
\includedetail[.8]{../bibsamples/bltdemo1}

\newpage
\nextblock
An example with author-year citations and the new \cmd{citetitle} command:
\begin{verbatim}
\documentclass{article}
\usepackage[bibstyle=authoryear,block=ragged]{biblatex}
\bibliography{bibdemo}

\begin{document}
See \citetitle{lcompanion} by \citeauthor{lcompanion} published in
\citeyear{lcompanion}.

\printbibliography
\end{document}
\end{verbatim}

\includedetail[.8]{../bibsamples/bltdemo3}

\nextblock
The practice files include a file \path{bibtex_biblatex_sample.tex} to
get you started with biblatex.

By now, there are quite a few biblatex styles (search for
`\texttt{biblatex-}' in the \nocite{ctancat}CTAN Catalogue), and
existing styles can be tweaked with options. Still, it is
conceivable that none of the existing styles are usable. And there
is no makebst (section~\ref{sec:makebst}) for biblatex. It is also
possible that the recipient has an antiquated \TeX{} setup or is
not willing or not able to handle biblatex. So it is too soon to
assign the older solutions to the dustbin.

\section{The \BT{} database format}
\label{sec:database}

This section describes the \BT{} database format. Like a \LaTeX{}
source, a \BT{} database is a plain text file. It has an extension
\texttt{.bib}, and consists of a series of records such as the
following:

\begin{verbatim}
@Article{biboostrum,
  author = "Piet van Oostrum",
  title = "Een tutorial over het gebruik van {Bib{\TeX}}",
  journal = "{MAPS}",
  volume = "30",
  pages = "66--86",
  year = 2004,
}
@Book{lcompanion,
  Author = "Frank Mittelbach and Michel Goossens",
  Title = "The {\LaTeX{}} Companion",
  Publisher = AW,
  year = 2004,
  Edition = "2nd",
}
\end{verbatim}
\label{verb:first_bib_example}

\newpage
\nextblock
Note the general structure: a \BT{} record consists of:
\begin{itemize}
\item The type of publication, \emph{e.g.}, article or book
\item A key, \emph{e.g.}, \texttt{biboostrum} or \texttt{lcompanion},
  which is used for citing
\item A list of fields
\end{itemize}
\nextblock
The list of required and optional fields varies with the entry
type. You can add additional fields, \emph{e.g.}, as comments for
yourself. Any field which is not required or optional will simply be
ignored.

For most fields, the values should be enclosed in braces \texttt{\{}
and \texttt{\}}, or in double quotes \texttt{" "}. Values which are
clearly numbers, such as years and volume numbers, may be entered
`bare'.

You should enclose \LaTeX{} code in an additional set of braces to
keep \BT{} from messing with it. You should do the same with
all-caps words.

As to accented characters, the safe solution is always to use
macros: \verb|{\'e}| rather than \texttt{\'e}, although with some
care accented letters may work ok, see section~\ref{sec:accents}.

\section{\BT{} editors and bibliography managers}
\label{sec:bib_editors}

For creation and maintenance of your \BT{} database it is best to
pick a program that uses \BT{} as its native format.

Our \TL{} installation includes the \BT{} editor \citetitle{jabref},
which is a Java program and therefore runs on all platforms where
Java is installed. On Mac OS, \citetitle{bibdesk} is a popular choice.

Editing manually with your \LaTeX{} editor is another good option.

A general-purpose bibliography manager may work for you, but check
its \BT{} export carefully.  The university offers access to
\citetitle{refworks}. However, last time I checked, its \BT{}
support left something to be desired.

\citetitle{zotero} is a popular Firefox extension for collecting and
managing references. It can create bibliographic entries from
\emph{e.g.} Amazon pages. Below the Zotero \BT{} export from such an
entry:
\begin{verbatim}
@book{voss_latex_2011,
	title = {{LaTeX} {Quick} {Reference}},
	isbn = {978-1-906860-21-9},
	language = {English},
	publisher = {UIT Cambridge Ltd.},
	author = {Voss, Herbert},
	month = sep,
	year = {2011}
}
\end{verbatim}
Further suggestions can be found at
\url{http://tex.stackexchange.com/questions/33619/}.

There are other services which create \BT{} entries, such as
\url{http://lead.to/amazon/en/}, or, if you have an ISBN number for a
book, you can go to \url{http://ottobib.com/}.
See \url{http://tex.stackexchange.com/questions/143/} for more
suggestions.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}\label{sec:bibexamples}

\begin{figure}
\includegraphics[width=\linewidth]{../screenshots/jabref}
\caption{\citetitle{jabref} \BT{} editor}\label{fig:jabref}
\end{figure}

Now let us have a more in-depth look at the \BT{} database
format by looking at a series of examples.

\begin{verbatim}
@TECHREPORT{canond2003,
  author = "Marcel Canoy and Sander Onderstal",
  year = 2003,
  title = "Tight oligopolies: {I}n search of proportionate remedies",
  number = 29,
  institution = "{CPB} Netherlands Bureau for Economic Policy Analysis",
  address = "The Hague",
}
\end{verbatim}
\texttt{TECHREPORT} is the type of the publication. Capitalization
is not significant in \BT{} entry types and field names.

The key \texttt{canond2003} is used by the various cite commands.

\texttt{\{CPB\}} is enclosed in braces to protect it against
\BT's automatic capitalization.

Also notice that the author field consists of two authors, each in
\emph{first last} format. The names are separated with `and'.

\subsection{Example: brace delimiters, alternate author syntax,
 accented letters}%\enlargethispage*{15bp}

\begin{verbatim}
@Misc{clementsgalvao2001,
 author = {Clementz, Michael P. and Galv{\~a}o, Ana Beatriz},
 title = {A comparison of tests of non-linear cointegration with an application
    to the predictability of {US} interest rates using the term structure},
 year = 2001,
 howpublished = {Mimeo, Department of Economics, University of Warwick},
}
\end{verbatim}
This example encloses values in braces rather than double
quotes. This makes it possible to use values which include double
quotes (nesting braces within braces is never a problem).

The author field uses the alternate syntax of \emph{last,
first}. The \BT{} manual (\citet{btxdoc}) has more to say about
the parsing of author's names.

Note that this entry has a different set of fields. The bibliography
style determines which entry types are recognized and which fields
are required or optional for each entry type.

Again, braces around \texttt{US} ensure that \BT{} leaves
capitalization alone.

\subsection*{Accented characters}\label{sec:accents}

The above example includes a macro for an accented letter inside
braces: \verb+{\~a}+.  You can use accented letters outright, but it
requires care: make sure that the encoding, probably utf8, cp1252 or
latin1 (JabRef: ISO8859\_1), matches the \LaTeX{} source, and that
you include a preamble command
\begin{verbatim}
\usepackage[enc]{inputenc}
\end{verbatim}
with the right value for \emph{enc}. With the modern \TeX{} engines
\XeLaTeX{} and \LuaLaTeX{}, you should not load \package{inputenc}
since these engines always expect utf8.

\subsection{Example: a predefined abbreviation and a dummy field}

\begin{verbatim}
@string{AW = "Addison-Wesley"}
 ...
@Book{lcompanion,
 Author = "Frank Mittelbach and Michel Goossens",
 Title = "The {\LaTeX{}} Companion",
 Publisher = AW,
 year = 2004,
 Edition = "2nd",
 ignorablefield = "too fat for my backpack",
}
\end{verbatim}
You can define abbreviations with \texttt{@string} entries. You can
also create a \texttt{.bib} file with \texttt{@string} entries, and
load it before the actual database file.\enlargethispage*{26bp}

This entry also uses a dummy field \texttt{ignorablefield} for
private information.

\subsection{Example: author names with a `von' part; number ranges}

\begin{verbatim}
@article{meycra2004,
  author = {Meyer, Jochen and von Cramon-Taubadel, Stephan},
  title = {Asymmetric Price Transmission: A Survey},
  year = 2004,
  journal = {Journal of Agricultural Economics},
  volume = 55,
  number = 3,
  pages = {581-611},
}
\end{verbatim}
\begin{verbatim}
@inproceedings{ricejava,
  author = "Istiqomah Istiqomah and Manfred Zeller and
    Stephan von Cramon-Taubadel",
  title = "Volatility and Integration of Rice Markets in Java, Indonesia",
  booktitle = "Tropentag 2005",
  year = 2005,
}
\end{verbatim}
These examples feature an author's name with a `von' part, first in
\emph{von last, first} syntax, then in \emph{first von last}
syntax. Again, \citet{btxdoc} explains handling of author's names.

Also note that \BT{} will expand the range \verb+581-611+ to
\verb+581--611+, producing a proper n-dash in the typeset output.

You can read a full description of the \texttt{.bib} format in the
original \BT{} documentation, \citet{btxdoc}. This documentation
doesn't cover extensions from, \emph{e.g.}, the Natbib- and biblatex
packages and corresponding bibliography styles.

\section{The url field}

Some bibliography styles, including styles created with
makebst/custom-bst, support an url field. It is even required for
the biblatex \texttt{online} entry type. It is a good idea to load
the \texttt{url} package, to make sure that special characters such
as underscores and tildes are rendered correctly, and to enable
line-breaking inside the url.  \LaTeX{} source:
\begin{verbatim}
\documentclass{article}
\usepackage{natbib}
\bibliographystyle{plainnat}
\usepackage{url}
...
\nocite{biboostrum}
\bibliography{bibdemo}
\end{document}
\end{verbatim}
\BT{} entry:
\begin{verbatim}
@Article{biboostrum,
 author = "Piet van Oostrum",
 title = "Een tutorial over het gebruik van {Bib{\TeX}}",
 journal = "{MAPS}",
 volume = "30",
 pages = "66--86",
 year = 2004,
 url = "http://www.ntg.nl/maps/pdf/30_15.pdf",
}
\end{verbatim}
results in:

\includedetail[.8]{../bibsamples/urlbib}

\subsection{Urls in other fields}

If the bibliography style does not use an url field, you can include
an url in another field. `Howpublished' is a good option, but only in
combination with, \emph{e.g}., the Misc entry type, since it is ignored by
most other entry types. Alternatively, the `Note' field is supported
by almost all entry types.%\enlargethispage*{12bp}
\begin{verbatim}
@Manual{tamethebeast,
 author = "Nicolas Markey",
 title = "Tame {t}he {BeaST}, The B to X of {BibTeX}",
 year = 2005,
 note = "{\url{http://www.lsv.ens-cachan.fr/~markey/BibTeX/doc/ttb_en.pdf}}",
}
@Misc{some,
 author = "Au Thor",
 title = "Some title",
 howpublished = "\url{http://www.a.site.net/sometitle.html}",
}
\end{verbatim}
\LaTeX{} source:
\begin{verbatim}
\documentclass{article}
\bibliographystyle{plain}
\usepackage{url}
...
\nocite{*}
\bibliography{nourl}
\end{document}
\end{verbatim}

\includedetail[.8]{../bibsamples/nourlbib}

\nextblock
The \texttt{natbib} reimplementations \texttt{plainnat},
\texttt{abbrvnat} and \texttt{unsrtnat} of the corresponding classical
bibliography styles do provide a url field and do not require the above
workarounds.

More trickery for working around \BT's automatisms can be found in
\citet{tamethebeast} and in the \BT{} chapter of the \citetitle{faq}.

\section{Practice}\label{sec:make_entries}

Add entries to \texttt{bibdemo.bib} and check your work with
\texttt{testbib.tex} and the \verb+\nocite{*}+ command, as described
in section~\ref{nocite}.

A suggestion: Find a Wikipedia page with many references,
\emph{e.g.}  \url{http://en.wikipedia.org/wiki/Economics}. Locate
entries with enough bibliographic information and turn them into
\BT{} entries. Or get more bibliographic details, or even a complete
\BT{} entry via \emph{e.g.}  \citetitle{googlescholar} and other
resources mentioned in
\url{http://tex.stackexchange.com/questions/143/}.

\section{Troubleshooting}
\label{sec:trouble}

\subsection{Random things to try}

\subsubsection*{Rerun \LaTeX}

Maybe you just need another \LaTeX{} run to resolve the \cmd{cite}
commands.

\subsubsection*{Problems with old auxiliary files}

Sometimes it helps to start with a clean slate by getting rid of old
auxiliary files: click on `Clean Auxiliary Files...' on the Tools
menu and rebuild.

This may be necessary if an error or incompatibility in one of the
auxiliary files prevents \LaTeX{} from continuing. An
incompatibility may arise \emph{e.g.} if you change something in the
bibliographic options.

\subsubsection*{Input encoding}

Maybe there is a mismatch between the encoding of the \BT{} database
export and the \LaTeX{} source. In JabRef, there is an item `Default
encoding' under \menupath{Options / Preferences / General}, and an
item `Database encoding' for the current \BT{} database under
\menupath{File / Database properties}.

\subsection{JabRef}

Make sure you run only one copy of JabRef. In particular, do
  not load one \BT{} file into two JabRef sessions, which can
  easily happen.

Click \menupath{File / Save database} to make sure that
  \BT{} or biber gets up to date information.

\subsection{Get more information}

In \TS, try to get more detailed information, \emph{e.g.}, by
clicking on the log tab of the tabbed pane under the edit area.

Log files can also be useful, but it may be difficult to pick out
the relevant bits. The tabbed Messages pane under the edit area has
a Log File button for the \LaTeX{} log, but not for the \BT{} log,
which may be more useful. You can load the \BT{} log into \TS{}
anyway: click on \menupath{File / Open}. Make sure that `Files of
type' is set to `All files(*)' and then select
\texttt{filename.blg}, assuming that the \LaTeX{} file is called
\texttt{filename.tex}. Another file to look at is
\texttt{filename.aux}.

\nocite{btxfaq}
\nocite{biboostrum}
