{:title "Setting up and configuring org-ref" :date "2017-07-14" :tags ["LaTeX" "open-science", "org-mode", "science", "programming"]}

# Setting up and configuring org-ref

First published: 2017-07-14 Fri
Last updated: 2018-09-08 Sat

## Org-ref

I use org-mode to write research papers, grants, etc.
Org-ref is an excellent Emacs minor-mode made by John Kitchin that makes it easy to format citations in org-mode. I started using org-ref a few months ago but being a beginner to Emacs-lisp I had some problems figuring out how to customize the settings and export citations in a usable manner. John's documentation is great but I think it is lacking a few points that may be clear to experienced bibtex/org-mode users but were certainly not clear to me. Here I will describe what I learned about customizing org-ref citations.

## Setup

This is quite well documented elsewhere and on the github page but here is how I set mine up.
First, install it. I use use-package for almost all my packages after watching this video.

;; emacs-lisp from https://github.com/nkicg6/emacs-config
;; org-bibtex
(require 'ox-bibtex)

;; reftex
(use-package reftex
:commands turn-on-reftex
:init
(progn
(setq reftex-default-bibliography '("/Users/Nick/Dropbox/bibliography/library.bib"))
(setq reftex-plug-intoAUCTex t))
)
(use-package org-ref
:after org
:init
(setq reftex-default-bibliography '("~/Dropbox/bibliography/library.bib"))
(setq org-ref-default-bibliography '("~/Dropbox/bibliography/library.bib"))
(setq org-ref-pdf-directory '("~/PDFs")))



Here I installed and set-up ox-bibtex, reftex, and org-ref. Honestly I am not sure if you need the first two, but I installed em and it works now. Set your default bibliography location while you are setting up the other two as well, use-pacakge allows you to do it at the same time.
Next, make sure you setup you LaTeX to properly process your file with bibliography.

(setq org-latex-pdf-process
'("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
"bibtex %b"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))



When compiling a LaTeX document with citations, you actually need to run the compiler 4 times in order to get all the formatting and intermediate documents correct. This command takes care of that for you. To be honest I am not sure what the %o %f mean. I am fairly certain they are not Emacs-lisp string formatting specification, because %o is a base-eight representation of an unsigned integer… so they likely mean something to pdflatex instead. See my post on LaTeX setup for installing pdflatex with BasicTeX.

(setq org-latex-logfiles-extensions (quote ("lof" "lot" "tex" "aux" "idx" "log" "out" "toc" "nav" "snm" "vrb" "dvi" "fdb_latexmk" "blg" "brf" "fls" "entoc" "ps" "spl" "bbl" "pygtex" "pygstyle")))


I found that default on the internet and it makes org-mode get rid of all the temporary LaTeX files made on export.

## Use

Refer to John's video and guide for useage. Basically, C-c ] brings you to the helm references menu where you can choose the reference or type a key to narrow it. RET selects the citation. Note, You can choose multiple citations by selecting with C-SPC over the different citations in one turn. You can also just C-c ] when the cursor is over an already inserted citation to put another in.
A cool feature is the ability to choose the citation style. When you select a citation C-SPC push C-u RET. This will bring up a menu of different citation options like citep citet citeyear etc. These options are explained here but they allow you to format the in-text citations almost any way you want!
Now, just insert the path to your bibliography and a style link like so:

bibliographystyle:apalike
bibliography:~/Dropbox/bibliography/library.bib


wherever you want your bibliography to go. The style is any bibtex style you install or want, and the path is the path to your bibtex bibliography. I use Mendeley and I have it 'watching' my PDF directory and store my bibtex citations in my Dropbox folder as shown above.

## It's just bibtex!

Org-ref is definitely not 'just bibtex' but after some frustrating searching, I finally realized that the customizations are! If you try exporting with vanilla settings as is, you will get citations, but they will look horrible.

For instance this setup

#+TITLE: test
#+DATE: 2017-07-13
#+OPTIONS: toc:nil author:nil title:nil date:nil num:nil ^:{} \n:1 todo:nil

#* Test
citep:Benusa2017 and other like
of multiple sclerosis. These domains are involved with the initiation and propagation of action potentials and are structurally and functionally quite similar cite:Clark2016. Although they are similar in terms of their protein composition and function, previous work from
here is a link to my [[https://nickgeorge.net][website]]

bibliographystyle:apalike
bibliography:~/Dropbox/bibliography/library.bib



Produces this

Why brackets? I was really disappointed with the style on export. I looked all over for ways to specify the correct options in org-ref, getting more frustrated all the time.Then I realized… This is a bibtex setting, not an org-ref setting! I searched for ways to make the brackets round, no way does every bibtex user use square brackets, and I found the answer:
\usepackage[round]{natbib}
If you want to style your org-ref citations, add the proper commands to your #+LATEX_HEADER!
I made a YASnippet to format this with my common settings.

#+TITLE: ${1:insert title} #+DATE: (format-time-string "%Y-%m-%d") #+OPTIONS: toc:nil author:nil title:nil date:nil num:nil ^:{} \n:1 todo:nil #+PROPERTY: header-args :exports both :eval no #+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} #+LATEX_HEADER: \hypersetup{citecolor=black,colorlinks=true,urlcolor=blue,linkbordercolor=blue,pdfborderstyle={/S/U/W 1}} #+LATEX_HEADER: \usepackage[round]{natbib} #+LATEX_HEADER: \renewcommand{\bibsection}$0

*References*
bibliographystyle:apalike
bibliography:~/Dropbox/bibliography/library.bib



I often change #+OPTIONS but I like having the list to remind me what I can do. #+PROPERTY options are also common, as I don't want to add a ton of formatting to my source code blocks. Any header-args you specify will apply to all source code in the document. NOTE the :eval no argument prevents evaluating any source code, even interactively. So disable and refresh if you need this.

\usepackage[margins=1.0]{geometry} so I can customize margins. \hypersetup is super important for citations and links. you may have to tlmgr install it first. citecolor = black is needed because for some reason the default is light green… Search for the other options, but basically they are to style my links.

\usepackage[round]{natbib} makes your citations round (George 2017) instead of [George 2017].
\renewcommand{\bibsection} allows you to prevent the addition of a separate section called References before the bibliography. Explained in this tex stackexchange.

#+TITLE: test
#+DATE: 2017-07-13
#+OPTIONS: toc:nil author:nil title:nil date:nil num:nil ^:{} \n:1 todo:nil
#+PROPERTY: header-args :exports both :eval no

#* Test
cite:Benusa2017 and other like
of multiple sclerosis. These domains are involved with the initiation and propagation of action potentials and are structurally and functionally quite similar cite:Clark2016. Although they are similar in terms of their protein composition and function, previous work from
here is a link to my [[https://nickgeorge.net][website]]

bibliographystyle:apalike
bibliography:~/Dropbox/bibliography/library.bib



Now the export should look much better. So use org-ref, but use BibTeX to specify styling!