Setting up and configuring org-ref

Org-ref

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.

;; 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!

It's 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

bad_ref_export.png

Figure 1: Whats with the brackets?

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 yas-snippet 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
#+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}


#* 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!

better_export.png

Figure 2: Better!