From org file with local bibtex to LaTeX and PDF

vxlabs-emacs-org-ref-pdf-example.png
Screenshot of orgmode source, PDF preview on the right, interactive citation selection in the minibuffer. Click for full resolution.

I have (co-)written a few LaTeX documents in my time.

However, as I have been writing my life and lab notes and many of my technical blog posts in Emacs orgmode for the past few years, I wanted to see how one would go about using BiBTeX references in orgmode files (using John Kitchin’s org-ref package) such that they would render correctly in orgmode’s export LaTeX and PDF.

My use case is of course slightly different than the norm: I maintain my master bibliography using the wonderful Zotero software, and I prefer exporting document-specific BiBTeX files from that main database.

This post shows you how to do it.

Pre-requisites

  • Make sure that latexmk is installed on your system. This is one of the easiest ways to make sure that pdflatex and bibtex are executed in the correct sequence, and a sufficient number of times.
  • With M-x package-install RET org-ref install the org-ref package. This will enable interactive selection and insertion of bibtex references from your local bib file.
  • You should also have the ox-latex Emacs package installed. This is what gives orgmode its LaTeX output powers.

Emacs setup

In your init.el somewhere, use the following code to ensure that the orgmode LaTeX exporter invokes latexmk in the correct way:

(setq org-latex-pdf-process
    '("latexmk -pdflatex='pdflatex -interaction nonstopmode' -pdf -bibtex -f %f"))

A minimal but complete orgmode example

The usual org-ref workflow is that you use it to manage a single main BiBTeX file, which is configured in your init.el. As mentioned above, I prefer using small document-specific BiBTeX files.

This is what the first three lines sets up using an Emacs file variable. Note that the local bib file is specified without quotes of any kind. Also, because there’s no path specified, it lives together with the orgmode document itself, which I prefer.

# Local Variables:
# org-ref-default-bibliography: local-bibtex-file.bib
# End:

After this, I have two LaTeX-specific lines ensuring that the output PDF looks prettier than default. You can thank me later.

The third LATEX_HEADER line imports the natbib package, which means I have extra cite commands to differentiate between for example textual citing (the first example) and parenthetical citing (the second example).

#+LATEX_CLASS_OPTIONS: [a4paper, 11pt, colorlinks=true, citecolor=., linkcolor=black, urlcolor=black]
#+LATEX_HEADER: \usepackage{fourier}
#+LATEX_HEADER: \usepackage{natbib}

#+TITLE: Example orgmode to LaTeX

* Introduction

  This is that really difficult intro spection, as was also
  demonstrated by cite:huang_identification_2016.

* Conclusions

  This is the even more difficult final section. We will now use a
  parenthetical citation citep:meyer_four-level_2012.

Finally, very importantly, I have the orgmode orgmode markup to select a suitable bibliography style, and again to specify the bib file. This will get automatically translated to the suitable LaTeX or even HTML versions.

Putting it all together

With something like the example above in your orgmode file, and a suitable bib-file, you can do C-c C-e l o to export to LaTeX, execute the latexmk command we specified above, and view the PDF.

In the screenshot at the start of this post, you can see what this looks like on my setup. I am using PDFTools for viewing the PDF inside of Emacs (this gets updated automatically whenever I rebuild the PDF).

You can also see the ivy-based completion as I’m in the process of interactively inserting a new citation into the document.

The default helm-based completion is more attractive, but it takes over the whole display, which is why I made use of ivy for instruction’s sake.

Export Zotero PDFs with BibTeX key filenames

This is just in from the department of silly Zotero hacks:

I’ve recently started using the brilliant papercite wordpress plugin to publish a list of my academic publications. This is awesome, because I can just export my Zotero bibliography as BibTex, and hand the bib file over to papercite!

However, when one exports a bibliography from Zotero, the associated PDF files are exported with their full filenames (whatever these may be), whilst papercite expects all PDFs to be in a single directory, each named bibtex_cite_key.pdf, for example malan_voxel_2013.pdf.

Hmmm, how will we solve this?!

papercite_pdfs
My precioussss bibtex citation key PDFs!

I know, let’s hack the Zotero translators/BibTex.js again!!

Around about line 2520 of BibTeX.js (this is with Zotero 4.0.17.1), in the function doExport(), you’ll find the following:

for(var i in item.attachments) {
    var attachment = item.attachments[i];
    if(Zotero.getOption("exportFileData") && attachment.saveFile) {
        attachment.saveFile(attachment.defaultPath, true);

Change it into the following:

for(var i in item.attachments) {
    var attachment = item.attachments[i];
    if(Zotero.getOption("exportFileData") && attachment.saveFile) {
        if (attachment.mimeType == 'application/pdf') {
            attachment.saveFile('/tmp/' + citekey + '.pdf', true);
        } else {
            attachment.saveFile(attachment.defaultPath, true);
        }

After exporting any set of publications as BibTeX, with “Export Files” checked, you’ll find a tmp subdirectory in your export directory. This contains all of the associated PDF files, named according to the BibTeX citation key, which is exactly what papercite wants.

Let me know in the comments how this went!

Removing URLs from Zotero bibtex exports

When you export bibtex from zotero, it includes the URLs in the bibtex records. Some LaTeX bibliography styles include this information, and sometimes this is not what you want, for example because the URLs take up unnecessary space and are hard to wrap.

It’s quite easy to get zotero to export bibtex without the URLs.

  1. Go to Preferences | Advanced and click on the “Show Data Directory” button.
  2. Edit translators/BibTeX.js with your favourite text editor.
  3. In function doExport(), at around line 2040 in Zotero 3.0.7, change the “for (var field in fieldMap)” loop by adding a single line of code like this:
for(var field in fieldMap) {
    # only add the following line:
    if (field == "url") continue;
    if(item[fieldMap[field]]) {
        writeField(field, item[fieldMap[field]]);
    }
}

If your changes don’t seem to take, make sure that your text editor did not make a backup of the old BibTeX.js (vim does this, with an ~ appended), as Zotero could possible pick up the backed up version instead of your edited version.

Let me know in the comments if this helped!

Look! References without URLs!

Update on 2013-02-17: Added tip concerning editor backups of BibTeX.js (I ran into this problem myself).