LaTeX + Zotero + APA citations on 64-bit Windows

Background

I’ve always liked the idea of getting to grips with LaTeX as a document creation tool. Once the learning curve is over, I think it’ll be much better than something like Word to produce consistently-styled documentation, especially for the grad dip I’m currently doing. Although, since my grad dip is in Information Design, I find myself using Scribus most often – maybe LaTeX can do very flexible “designery” layouts, but I don’t think that’s its strength.

To get LaTeX to a state where it’ll actually be useful to me, I needed it to work with Zotero, which I use as my citation manager, and to be able correctly format citations in APA style. This turned out to be surprisingly tricky.

[U|Li]nix aficionados will tell you that the strength of the system is that you can chain (lots of) little utilities together to do the job. Big, monolithic pieces of software are not the Unixy way. While this sounds great in principle – I also like little utilities that work well and that can talk to each other – it can be like herding cats when you’re not a *nix guru. The LaTeX distributions, including on Windows, are in seeming accordance with this philosophy, with its attendant advantages and drawbacks.

The rig

The environment I have is a Windows 7 x64 laptop. Plenty of memory and the hard drive is an SSD, but this doesn’t really make much difference in the greater scheme of things.

The LaTeX distribution I have is MiKTeX, version 2.9 – I chose it because it’s well-known on Windows, and because it has a great package manager. It installs the Latex core by default and is usable right away. But if you find you want to add a new function that’s not in the core (these are called “packages”), MiKTeX will install it for you (if you’re connected to the Internet) the first time you try and use it. I have the 64-bit version of MiKTeX (this becomes important later).

I’m currently using Texmaker as my LaTeX editor. I’m tempted to ditch that and start using Sublime Text instead (I use Sublime for other coding work, and I like its interface – and it has a nice LaTeX plugin). Texmaker might be better if you’re a “power user” of LaTeX, but I’m far from that. However, it does have a lot of good built-in controls for doing the document-generation steps.

Finally, of course, I’m using Zotero as my citation manager, inside Firefox.

The joy of LaTeX

I’m not going to describe the installation procedure or how the software works on the basic level. Like Linux, there are a lot of distributions out there, and there are a lot of packages out there that do the same thing in very different ways. LaTeX is currently evolving and new packages are being developed and enhanced all the time.

This results in the major drawback that basic tutorials may reference some really ancient version of LaTeX that does things in the most convoluted-possible way. Then you find out some package does it much more easily… oh, no, there are three packages that purport to do it much more easily. And then there are lots of discussions about which one is best, which for a beginner, aren’t that helpful.

Some might argue that it might be best to follow the tutorial based on the old system, but if no-one is doing it that way any more in practice, then I think it’s counter-productive. I certainly wouldn’t advise anyone beginning Windows systems administration now to learn DOS in depth. Although it could be seen to be an advantage to knowing how the command-line works (I have one multi-line DOS script on these pages – the first I’ve written in about 5 years –  it should pretty much be one-liners and Powershell these days).

Getting to the point, citations and bibliographies have sprouted a lot of variations over the years in the LaTeX world. What I’ve done is select the components that will most easily do what I need.

The result I’m aiming for

This is the document I want to produce. A bunch of citations that are done in different ways in the body of the document, which then are formatted in a nice APA-style bibliography at the end.

Please don’t use this as a valid example of correct APA. I may well have errors (I think my second in-line citation is a bit dodgy).

A LaTex-formatted document with generated citations and bibliography

Example document

The code

The code below was used to produce the above document. I’ve added some extra line breaks to make it easier to read. Remember, LaTeX doesn’t care about line breaks anyway. I’ll explain the salient parts of the code in the next sections.

% Creating bibliography from Zotero
\documentclass{article}

\usepackage[utf8]{inputenc}
\addbibresource[location=remote]
{http://localhost:23119/better-bibtex/collection?/0/ABC123X.biblatex&exportCharset=utf8}
\usepackage[english, american]{babel}
\usepackage{csquotes}
\usepackage[style=apa,sortcites=true,sorting=nyt,backend=biber]{biblatex}
\DeclareLanguageMapping{english}{american-apa}

\begin{document}
\author{The Author}
\title{Bibilography with \LaTeX{} and Zotero}
\date{\today}
\maketitle

\section{Introduction}
\LaTeX{} is a document creation system developed by Leslie Lamport.

\section{Some citations}
Here are some citations that are listed in different ways.
\begin{itemize}
    \item An EDRMS is challenging to deploy, say \textcite{DiBiagio}. 
Almost as challenging as constructing a document in \LaTeX{}.
    \item Look at \citeauthor{Bijker1997}'s seminal article 
(\citeyear{Bijker1997}) on bicycles, Bakelite and bulbs.
    \item Technology may be deterministic. \autocite{Chandler}
    \item What on earth is "re-modernization"? \autocite{Latour2003}
\end{itemize}

\printbibliography
\end{document}

Getting the parts together

To get this working, we needed to set up Zotero, then LaTeX. LaTeX needed some new packages, and the code created in the right way.

Zotero

Setup

The core of the solution is the Better Bibtex (BB) add-on to Firefox. What it does is create an export of your Zotero citations in Bibtex format (used by LaTeX), which you can access dynamically. That is, you don’t need to manually export a Bibtex file and then copy it laboriously into your LaTeX document.

I’m not going to get into all BB’s features – also since I feel that the documentation is a bit incomplete for the beginner – but this is what I did to get it working for my purposes. The main things to know are:

  1. I’m just letting Better Bibtex auto-generate the citation codes that you’ll use in your LaTeX document. It’s easy to specify your own. Just remember that if they are auto-specified, they don’t currently sync online (if you’re using the online Zotero synch, and why wouldn’t you?).
  2. I’m doing a “pull export” of the citations via the http engine that Zotero provides. There’s some comment about using curl to do the export, but since it’s not explained, I’m not doing it.
  3. You need to install the add-on from the web page – it’s not on the Firefox addons site.

Once you’ve installed BB, open up Zotero and ensure you have the new BB add-on tab showing up in the Zotero preferences.
Screenshot of Better Bibtex options

Check the following preferences:

  • The Enable export by HTTP option is Enabled. Very important!
  • Set Export as Unicode to Always. This may not be required, because we’re going to specify Biblatex, but best to be sure.
  • I also set the option to export DOI only when a reference has both a DOI and a URL. This is because all my references that have both were gathered from an online subscription service (so I think the DOI only is sufficient). It’s up to you what you prefer, but I was editing all my citations before I noticed this setting.

Info for the next steps

To build the bibliography in the document, you need:

  • The URL for the Zotero collection you’re using
  • The cite codes you’ll use in-line within the document

What I did was arrange the citations I was going to use for the document in one folder, and then get that URL. You can naturally use URL for your top-level folder, but if you have your citations arranged in sub-folders, you’ll need to enable the recursive option in the Better Bibtex preferences.

  1. Right-click on your citations folder and select BibLatexURL.
    screenshot of right-click dialogue

  2. A dialogue box pops up with the URL. It looks like http://localhost:23119/better-bibtex/collection?/0/ABC123X.biblatex. Simply select it, and copy and paste it into your TeX document (anywhere will do for now). Note that the http://localhost:23119/better-bibtex/collection?/0 is the default URL for your full collection.
    URL pop-up box

  3. Paste the URL into your browser, and you should see your citations showing up as a page in Bibtex format. If not, maybe Zotero isn’t running with http enabled. screenshot of bibtex citation in browser
  4. To find the citation keys that you’ll need to use in-line in your document, open each citation and look for the Extra field. You’ll see bibtex: followed by some text. This text after the colon is all you need for your citation key to that cite. In my example, it’s simply Chandler.Screenshot showing location of cite field

That’s it for what you need to glean from Zotero!

Changing biblio generation

What we do for this document is change the bibliography-styling system from the default bibtex to the much newer biblatex

biblatex and biber

For biblatex, this link summarises a bunch of reasons why it should be used, but the reasons that I am using it is that it has a lot of very good pre-baked citation formatting styles (such as APA!), AND it allows us to use our URL from our Zotero database (as a “remote” source).

As well, we’re changing the back-end bibliography-generating engine from bibtex to biber. This supports UTF8 natively, and works well with biblatex and its “remote” feature. The reason the UTF8 is important is that one of my example citations has an mdash (“long dash”) in the title, and I’d have to put it in manually using the old bibtex format. If you don’t write 100% in ASCII, you want this!

biber doesn’t exist in 64-bit MiKTeX!

This won’t apply if you’re using 32-bit MiKTeX or maybe another LaTeX distribution. However, I was pulling my hair out when biber didn’t work for me at first. And it was because it wasn’t installed – it’s a default package in the 32-bit version of MiKTeX. So you need to download the file and extract biber.exe to the $texfm$\miktex\bin\x64 folder ($texfm$ is the folder where MiKTeX is installed – mine’s “C:\Program Files\MiKTeX 2.9”). This link’s comments discuss why it’s a bad idea to do that, and how to create another folder to stash “custom” software, but I could not be bothered. It works fine.

Once I installed the biber.exe file, I needed to open the MiKTeX Admin options and click the Refresh FNDB button.
MiKTeX database rebuild

Finally, since I’m using Texmaker to edit my TeX documents, I needed to update the command to build the bibliography – bibtex by default. In the Configure Texmaker options, I changed the bibtex command to biber % instead.
biber config in Texmaker

TeX document elements

Now that all the prep has been done, there are a few elements that need to go into the document to make it work. This is not going to describe the packages you use to create the base document, or text formatting, like \documentclass{article}, \begin{document} etc. I’m concentrating on the elements required to do the citations.

Including the packages

These all go into the document preamble.

The whole document is using Unicode/UTF8 for its character format to ensure special characters come across nicely, and that gets instantiated by the inputenc (INput ENCoding) package.

\usepackage[utf8]{inputenc}

As discussed at length, we’re using the http interface into Zotero, and in line 5 of the document code, I’ve included the URL for the collection we copied from Zotero. I’ve split it onto two lines to make it easier to read.

\addbibresource[location=remote]
{http://localhost:23119/better-bibtex/collection?/0/ABC123X.biblatex&exportCharset=utf8}

\addbibresource can be used to point to a file [location] on disk or via a network. The latter is what we’re doing here, even though the network in this instance is located on the same computer as the document. The Zotero collection URL must be in curly brackets {}.

Next, on line 9, we’re saying we’re going to generate the bibliography using biblatex (and not the default Bibtex). All that’s really needed to do so is \usepackage{biblatex} – it will generate citations and a bibliography fine – but I want to use the APA style specifically. I also specify backend=biber in the options inside the square brackets []. Biblatex defaults to the biber backend to build the biblio, but you get annoying warnings in the output (and it may be that you change the default for some weird reason and forget).

\usepackage[style=apa,sortcites=true,sorting=nyt,backend=biber]{biblatex}

Finally, the biblatex-apa package (that provides the APA style) requires US English language settings to generate the citations properly. I don’t write in US English, so all this stuff below is simply to get the language settings right to generate APA. babel is a nice package that a whole bunch of language localisation stuff. csquotes helps with reading/creating nice quotation marks depending on the language setting and works well with babel. I can say that omitting these meant the bibliography came out riddled with errors; also, when you RTFM, the biblatex-apa documentation states that US-English is required.

\usepackage[english, american]{babel}
\usepackage{csquotes}
\DeclareLanguageMapping{english}{american-apa}

Adding citations

In the body of my Tex document, you can see a bunch of different ways of creating citations from line 25 onwards. The default citation style for APA is the (Author, Year) format. This format is automatically generated by the \autocite command from biblatex-apa.

To insert one of your citations, you need the citation key from the appropriate Zotero reference (in the Extra field). We found the key for Chandler earlier, so we insert it as the key for the \autocite command, between the curly brackets {}. You place it exactly where you want your inline citation to appear in the document.

Technology may be deterministic. \autocite{Chandler}

This results in the text (n.d. is because the citation is not dated):

Technology may be deterministic. (Chandler, n.d.)

If I used \autocite{latour2003} instead, I’d get the following text (although Latour didn’t write it):

Technology may be deterministic. (Latour, 2003)

Remember that the “2003” has got nothing to do with the {latour2003} citation key I used. I have more than one citation from Latour in my Zotero database, and so Better Bibtex added the year to make it unique. If I had only one Latour citation, then {latour} would have most likely been the code, and would have generated exactly the same citation. biblatex reads the year part of the citation from the proper field in the bibtex URL file.

While I’ve shown a few ways of inserting citations, you should consult The ex­am­ples in the APA style guide document at the biblatex-apa site for many more.

Generating the bibliography

Once you’ve inserted all the citations in your document, there is a terribly complicated process to insert the bibliography.

Go to the point in the document you want to insert the biblio and add the following code:

\printbibliography

That’s it. The APA-formatted bibliography will be generated in its entirety based on the citations that you inserted into your document, formatted correctly, and inserted at the specified location, complete with the heading Bibliography.

This really demonstrates the power of LaTeX – once you’ve got all the preamble sorted out, creating the document is very simple. Once you have a nice template that does what you need, you can recycle it over and over and over.

Compiling the document

Once all this has been done, set up, coded, inserted, you can compile the document. The usual routine for compiling a document is to run latex command to build the base document. In MiKTeX, I’m using pdflatex for this step.

If your LaTeX distribution doesn’t auto-download packages for you, you should download and installed the required packages listed above.

Multiple compilation steps

First and foremost: make sure Zotero is running and you can connect to the citation collection URL!

For creating a document with citations, you need to run the pdflatex several times, and the biblatex/biber command to build the bibilography file. The sequence is as follows (if you’re running it from a command line and not a GUI tool):

  1. Ensure Zotero is running!
  2. pdflatex document.tex – creates the base document, no citations (just question marks as placeholders)
  3. biber – to grab and format the bibliography
  4. pdflatex document.tex – format the document with citations correctly inserted
  5. pdflatex document.tex – format the document again to take care of any page numbering problems

This is the same routine I used with MiKTeX, although they conveniently let you bundle them all into the “QuickBuild” command. Naturally, if you’re not mucking around with citations or indexes, you just need to run pdflatex, and your document is done.

The first pdflatex command loads all the packages that have been specified in the document. With MiKTeX, if they’re not found, it will go ahead and download and install them from the Internet. To save some time, it’s easier to use the MiKTeX admin console to install them in advance. Also, I had a little trouble with the biblatex-apa package. It didn’t want to autoinstall when I ran the pdflatex command from Texmaker, but it was fine from the MiKTeX admin console.

Completed!

Once you’ve compiled the document a bunch of times with pdflatex and biber, you should have a really shiny PDF document with your citations inserted just so. Scroll back up to the shot of the PDF for evidence.

Complete checklist

Here’s all the steps you need to get this working:

  1. Install Better Bibtex into Firefox
  2. Ensure the BB settings show Export as Unicode and Enable export by HTTP.
  3. Get the citations URL for your Zotero collection
  4. Ensure you can open the citations URL in your browser
  5. Install 32-bit biber if you have 64-bit MiKTeX.
  6. Make any required changes for biber instead of bibtex in your Tex editor if you compile documents there.
  7. In the Tex file, insert the \usepackage commands for the required components in the preamble
    • \usepackage[utf8]{inputenc}
    • \addbibresource[location=remote]{BetterBibtexURL}
    • \usepackage[style=apa,sortcites=true,sorting=nyt,backend=biber]{biblatex}
    • \usepackage[english, american]{babel} – required for APA style
    • \usepackage{csquotes} – required for APA style
    • \DeclareLanguageMapping{english}{american-apa} – required for APA style
  8. If your Tex compiler doesn’t auto-install the required packages above, install the packages.
  9. Insert citation codes where required into the document, using the citation key from the Extra field from each Zotero reference – \autocite{key}
  10. Insert \printbibliography where you want your bibliography to be printed
  11. Make sure Zotero is running and the references URL is available
  12. Compile the document four times, using pdflatex -> biber -> pdflatex -> pdflatex. If you’re using plain latex rather than pdflatex, you’ll have an extra step to compile a PDF, if that’s the desired format
  13. Completed!

Final tip: If you get very stuck, go to http://tex.stackexchange.com, and search there for help. If there’s no info that seems relevant, ask the gurus there on advice to solve your problems. Remember to ask sensible questions and show your working.

Advertisements
This entry was posted in Non-work and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s