[mathjax]
It’s no secret that physicists love using LaTeX to write papers. This has many practical advantages, such as the ability to completely unlink your content from the formatting, very flexible layout tools and a veritable smorgasbord of packages to do everything from change the colour of your text to allow you to programmatically create plots and vector graphics. This is all great but it comes at a cost; it’s got one hell of a steep learning curve. When I first picked up the language at undergrad it seemed daunting to me, and I was a relatively seasoned programmer even at that time. I can only imagine what other, less experienced folks were thinking. The honest truth is that as long as you are aware of the basics of the language, you can muddle by and make some very nice looking, well typeset documents. The one thing that doesn’t come quite as easily though are citations and references. At first, we were taught to simply manually type them using guidelines for the referencing style we wished to use. Although this approach works, it’s very time consuming, prone to errors, and just generally seems deeply unsatisfying when the rest of your document is compiling to PDF at the push of a button. Even then I thought there had to be a better way. The good news is, there was.
Enter, BibTeX
BibTeX uses very similar syntax to LaTeX to effectively markup the important information about any publications that you may wish to include in a LaTeX document. Here’s a simple example of a BibTeX record:
@ARTICLE{1998ApJ...500..525S,
author = {{Schlegel}, D.~J. and {Finkbeiner}, D.~P. and {Davis}, M.},
title = "{Maps of Dust Infrared Emission for Use in Estimation of Reddening and Cosmic Microwave Background Radiation Foregrounds}",
journal = {\apj},
eprint = {astro-ph/9710327},
keywords = {COSMOLOGY: DIFFUSE RADIATION, COSMOLOGY: COSMIC MICROWAVE BACKGROUND, ISM: DUST, EXTINCTION, INTERPLANETARY MEDIUM, INFRARED: ISM: CONTINUUM, Cosmology: Cosmic Microwave Background, Cosmology: Diffuse Radiation, ISM: Dust, Extinction, Infrared: ISM: Continuum, Interplanetary Medium},
year = 1998,
month = jun,
volume = 500,
pages = {525-553},
doi = {10.1086/305772},
adsurl = {http://adsabs.harvard.edu/abs/1998ApJ...500..525S},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
This, conveniently, is the BibTeX record for a paper that I’ve been reading lately which just so happens to be the most cited astrophysics paper on ADS. Let’s just point out some of the simple syntax. We start off on line 1 with the @ARTICLE which simply describes what kind of document it is we’re referencing. As with a lot of cases, this is just a paper from a journal, referred to in the BibTeX parlance as an article. There are a list of possible document types and their labels available here. After defining the type of document you can define the record associated with it using curly braces. The first item, directly inside the opening brace, is the cite key. This is what this particular publication will be known as when we put it into LaTeX later on. It doesn’t really matter what this is as long as you remember it. I generally just pick the name of the first author and the year. So for example, I would replace ‘1998ApJ…500..525S’ with ‘Schlegel1998’. After this we have a whole list of properties of the entry, each separated by a comma. This is structured like a key-value pair where the key and value are separated by an equals sign. The first field is the author field, which contains a list of authors for the paper. Some properties are contained inside curly braces, and this is just one of those. We can also include additional notation in this. The last name of the author is contained within curly braces and any optional initials can have a tilde in front of them. You can separate the authors using ‘and’. The next property is the title, and this pretty much does as it says on the tin and contains the title of the publication. Because it’s a string, this should be inside speech marks. Next we have the journal, year, month, volume and pages. This contains information about the year of publication and the journal in which it was contained. This includes the year of publication, month of publication and the volume and page numbers of the journal that the publication can be found in. The remaining fields aren’t particularly important, but if you’re in astro chances are you’ll come across them so I’ll just go over them:
- eprint – You’ve heard of arXiv.org, right? Excellent. Well, this is the identifer it’s known by over there. If you copy this and search for it on arXiv.org, the arXiv eprint version of this article will pop right up.
- keywords – As is often the case, adding keywords to your articles makes it easier to search for what you’re looking for and for authors to make their work seen. This is where the keywords associated with a given article are stored in your BibTeX database.
- doi – In official online parlance this stands for Digital Object Identifier. This is simply an identifier that can be used to uniquely identify a piece of information all over the internet. If the publication in question has been submitted for publication, chances are it’s been assigned one of these. These can be used to great effect by going to the official DOI website and pasting it into the text box there. When you click the resolve button, it’ll take you straight to the paper in question, wherever it may happen to be hosted / published.
- adsnote / adsurl – These two are simply stuff that is added in by the SAO / NASA Astrophysics Data System (ADS). This is on here because I copied the BibTex for this entry from the ADS website. This is by far one of the easiest ways of getting the BibTeX for your own documents.
That’s the basic format of an entry sorted, but what do you do with them? Well the great news is that they are pretty much all just self contained blocks of markup so you can copy and paste them all into the same file with no worries of them interfering with each other. I’ll now take you through the process of compiling your very first LaTeX document utilising BibTeX.
Basic Usage of BibTeX with LaTeX
Now that I’ve taken you through the basics of BibTeX and how it can be used to represent a journal article that you may want to reference in a paper, I’m going to go through how you go about popping this into your LaTeX document. For this I’m going to recommend a nifty little package called natbib. This package will allow us to import the BibTeX file, set the bibliography style and cite it within the text using a couple different macros. You can work with citations without natbib, but using it will give you a lot more flexibility. Here’s the basic structure of our LaTeX file:
\documentclass[a4paper, 10pt]{article}
% First use the package natbib
\usepackage{natbib}
% Now we can set the bibliography style.
\bibliographystyle{authordate1}
\newcommand{\apj}{ApJ}
\begin{document}
\title{Beginning with BibTeX - Making Referencing in \LaTeX\ as Easy as Pi}
\author{Sam Morrell}
\maketitle
\section{Introduction} % (fold)
\label{sec:introduction}
In this block of text, we would like to cite the paper by \citet{1998ApJ...500..525S} using the textual citation. We can also use a parenthetical citation when we want to reference something at the end of a statement \citep{1998ApJ...500..525S}.
% section introduction (end)
% Include the bib file and the bibliography here
\bibliography{bibtex}
\end{document}If you’re familiar with LaTeX this should be immediately recognisable as the beginnings of a document. However, this document is also also enabled with bibTeX references. Lets go through what we need to include to get this working.
- First off we need to import the package that will let us use BibTeX in our documents. My personal recommendation for this would be natbib. This package comes with a load of features that should get your references perfectly on the page.
- The next part is the macro \bibliographystyle, which more or less does what it says on the tin. This macro is used to define the style of citations and references you want to appear in the document. On this occasion I chose authoryear1 because I’m used to using a similar format, however plainnat should do nicely if you’re trying to stick to a more Vancouver-ian referencing style.
- Next we come to the main body of text and the main bit of magic that lets this all work. Assuming that you’ve kept the default, you can use \citet and \citep to cite references in one of two ways. \citet allows the reference to be slipped conveniently into body text and presents the paper in the context of a sentence. Alternatively, the \citep macro allows you to cite a reference at the end of a sentence in parenthesise where it doesn’t naturally fit within the flow of the sentence.
- The final touch here is actually showing the references within the document. Assuming that your BibTeX document is called bibtex.bib, you can accomplish all of this using the single macro, \bibliography.
Just a small note, some citations come with short codes for journals such as \ApJ, which is a shorthand for The Astrophysical Journal. By default the document won’t compile, as the command is undefined. There are various solutions that solve this problem, but for the sake of this demonstration I’ve just defined it manually at line 11 of the above document. Before we compile with pdflatex or your TeX of choice there are a couple more steps involved in getting this working smoothly.
Some Details on How BibTeX Works
If you don’t want the want the details of how BibTeX actually compiles documents then feel free to read on, but knowledge of this process can be useful when things aren’t working how you expect them to, so I think it’s useful to include. When you compile the document with LaTeX a load of other files get created and written to in the same directory. Among these is one with the file extension .aux. This file contains a load of information about the document that you’re compiling. This allows other pieces of software that tie in to LaTeX to be able to read and write information about the document without having to parse the whole thing themselves. Included in this file is the chosen bibliography style and the citations that have been included in the document. When you run BibTex it reads in this file and your .bib file, detects the bibliography style and sets to outputting the required citations in the correct file. When it’s finished you should see a new file with a .bbl extension has been created in the same directory. This is the file that contains the LaTeX which will be included in your document as the bibliography. It’s only text so open it now and see for yourself. The interesting thing about this process is that regardless of the number of entries in your .bib file, BibTeX only outputs the references that are used in your document. This is because it reads the citations from the .aux file and only includes the ones that it knows you’ve cited. The only piece of the puzzle remaining is for LaTeX to replace your \citet and \citep commands with an actual citation that links to an item in the bibliography. In just the same way that LaTeX does, BibTeX writes to the .aux file what each citation is to be replaced with when the document is compiled. When LaTeX reads this in, natbib picks these up and replaces accordingly. At the end of this process is a document with citations and a bibliography in style of your choice with minimal effort on your part. Great, huh?
The Workflow
There is only one slight disadvantage to BibTeX, and that is that you may need to add a couple more steps to your compiling workflow. This is because you need to run LaTeX once to generate the .aux file, then BibTeX to generate the references and then LaTeX again to compile it all together into the finished document. Rinse and repeat. You can set up a shell script to compile for you if you are particular inclined, however there are some great pieces of software to make this process a breeze. If you’re into purpose made LaTeX authoring software, my hearty recommendation is texmaker. The Quick Build command gives the option of including BibTeX in the process. This, in addition to the handy library of symbols and commands and pretty competent auto completion, makes texmaker a great choice for beginners wanting to ease up the learning curve of LaTeX.
My personal choice is to use a combination of my Sublime Text and LaTeX Tools. This does require first installing the Package Control, the Sublime Text package manager, into Sublime Text, however the whole process is fairly easy and well documented. This comes with some really neat auto completion macros that will save you a lot of typing and a great build option which will automatically do all the necessary steps for you to compile your document; yep, ctrl / cmd + B does everything. This includes full support for BibTex, even down to auto completion of citations so you don’t have to go hunting for the label ever again. It includes a whole slew of other great features that are all documented on the. When the document is compiled it will also open it up in a PDF reader and keep it updated when you recompile. For macOS if uses Skim which should work as long as Skim.app is in /Applications. On Windows it will open in Sumatra PDF which may require some configuration for you to point it to the correct place. However, this is a matter of opening Preferences > Package Settings > LaTeX Tools > Settings – User and setting the windows.sumatra value to the correct path; which in most cases should be “C:\\Program Files\\SumatraPDF\\SumatraPDF.exe”. Finally, on Linux it should play ball with any PDF reader that can be started from a command line, however by default it looks for Evince.
I hope this has been useful to those of you wanting to save yourself hours by not writing out all of your citations by hand. When I embraced this myself, I knocked hours off of compiling my LaTeX documents and I hope it does for you as well. One key thing to remember about LaTeX and the tools that are involved in working with it is that Stack Exchange is your friend. It is a widely used piece of software, which means that if you type the error into your search engine of choice, the chances are that you’ll find someone else who has had the same problem and managed to get it sorted. I’ve so far managed to solve every LaTeX related problem I’ve had in this exact way. As ever, if there is anything in this document that you think is incorrect or could do with some clarification please do let me know. Until next time, thanks for reading.
