Introduction

This is intended to be a minimal emacs starter kit for people doing academic writing with a combination of R, LaTeX, and/or markdown. I wrote this because I got tired of saying something along the lines of: “No, I don’t use Rstudio. I use emacs, but it’s kind of a pain to get set up…”

No more. Now that I’ve written this I can shamelessly recommend it to people.

So this should get people the absolute bare minimum needed to get started using R/latex/markdown/rmarkdown/sweave/knitr in emacs.

As far as I know, this works on all versions of emacs greater than 25.3 across Linux, Mac, and Windows operating systems. If you run into a problem, feel free to email me or create an issue in this github repo.

Installation

Step 1: Install Emacs

Installation instructions for Emacs are OS specific:

Linux/BSD

Use your package manager

MacOS/OS X

Use homebrew:

brew install emacs --with-cocoa

Note that you might also need to install a spell checker. I recommend aspell:

brew install aspell

Windows

These instructions are a condensed version of the official README. If you run into problems, consult the README:

1. Go to this website
2. Download the latest version of Emacs (25.3 as of this writing)
   1. If you run a 64-bit system (you probably do), select the 64-bit version. For Emacs 25.3 that’s emacs-25.3-x86_64-w64-mingw32.zip
3. Unzip that file into a directory where you want to install Emacs (C:\Program Files, for example)
4. Run the runemacs.exe file inside the newly-created bin folder
   1. Optionally, you can add Emacs to the start menu by running the addpm.exe file

Step 2: Clone this repo

Now that you’ve installed Emacs, you’ll want to use these customizations so it works with R/markdown/latex/git etc. The easiest way is to do that with git, if you know how to use it.

Note for Windows users: You’ll have to figure out where Emacs thinks your “home” is. One way to do this is to open Emacs, and do C-x d (hold control, press x, release, then press d). It’ll ask you what directory you want, tell it ~ and note wherever it opens. For me (Windows 10), this was C:\Users\<myusername> but it may be different for you. You can also set up an environmental variable HOME as described in the wiki.

If you know git:

git clone https://github.com/jabranham/emacs-for-social-science.git ~/.emacs.d/

Windows users will need to replace ~ with wherever Emacs is calling home, as described above.

If you don’t know git:

Download a zipped version and extract it into ~/.emacs.d/.

Windows users will need to replace ~ with wherever Emacs is calling home, as described above.

Step 3: Optionally install other programs

If you want spell check to work, you’ll need to install a spell checker. Either aspell or hunspell works fine.

You’ll also probably want to make sure you have whatever program(s) you want to work with installed: R, LaTeX, git, pandoc, etc.

Step 4: Start Emacs

When you start Emacs, it should start downloading and compiling some files (packages). Just sit back for this part - it’ll take a minute. You may need to answer “y” when prompted about saving abbreviations. It will output warnings and some messages - you may ignore these. If the process stops, quit Emacs and restart it.

If you restart Emacs and are presented with an ugly screen with some links to a tutorial, walkthrough, and others, and NO errors, then everything has set up successfully! You’re ready to go.

Immediate customization

You’ll need to set up a few things like telling Emacs where your big .bib file is. All of these are in the init-emacs.org file near the top under the section “Your customizations”. So, for example, to let Emacs know about your big bib file, you would change the value of the my/bib-file-location to wherever your bib file is located on your computer.

Usage

Many of Emacs’ keybindings look something like C-c or M-c. The first says control-c, the second meta-c. The meta key is usually alt. M-x provides a searchable list of commands you can run, so if you can’t remember the exact name, you can look it up using M-x. There is a general-purpose tutorial you can access with C-h t. It will teach you most of the basic commands necessary to move around inside Emacs. I highly recommend skimming through it.

You should be set up and ready to use Emacs for R, (r)markdown, latex, and git. Emacs will also support a lot of other programming languages out-of-the-box.

To open a file, do C-x C-f, which opens a buffer showing the files and folders of your current directory.You can open a file by selecting it (navigate up/down using the arrow keys or C-p / C-n). To go up a directory, hit C-l. To go down into a folder, have it selected and hit C-j. You can learn more basic Emacs functionality by going through the tutorial with C-h t.

Emacs thinks about “buffers” in terms of a major mode. So when you’re editing an markdown file, emacs is in markdown-mode. You can learn about the current major mode, including useful keybindings, by pressing C-h m (C-h is help, then m for mode). So if you do that when you’re editing an R script, you’ll learn that C-RET (control-enter) is bound to ess-eval-region-or-line-and-step, which (as the function name suggests), will evaluate a region if selected. If not, it will evaluate the line that point (your cursor) is on, and then it will “step” (i.e. move to the next bit of code).

If you want to learn about a function, you can press C-h f, and if you want to learn about a variable C-h v. Emacs 25.1 introduced C-h o which combines those two help functions (i.e. searches variables and functions). Here’s a quick list of the commands I use most frequently in the modes I’ve set up for you:

References

One of the best things about Emacs, compared to other editors (e.g. TeXStudio, RStudio, etc) is reference management for latex and markdown files. So long as you set up my/bib-file-location at the beginning of init-emacs.org to point to your big .bib file, this should work out-of-the-box for you.

C-c C-r will let you browse and search your bibliography from any window. You may also insert citations in latex and markdown using C-c C-r, searching for the entry, then pressing RET (enter). This is due to ivy-bibtex, which we set up in the init-emacs.org file. You can do a few other things than simply inserting a citation; view your options by highlighting a reference and hitting M-o instead of RET.

R (ESS)

ESS is short for Emacs Speaks Statistics and here are a handful of the most useful keybindings. If the name of the function isn’t enough, you may type C-h f then the name of the function to find out what it does. Remember that there are tons more functions, most of which you can access and search with M-x, or learn about via C-h m (help mode).

Keybinding	Function name
C-RET	ess-eval-region-or-line-and-step
C-M-x	ess-eval-region-or-function-or-paragraph
TAB	ess-indent-or-complete
S-_	ess-smart-S-assign
	ess-rdired (for listing R objects)

Latex (AuCTeX)

AuCTeX rocks as a latex editor. Here are some of the more useful keybindings it gives you:

Keybinding	Function name
C-c	TeX-command-master
C-c C-e	LaTeX-environment
C-c C-m	TeX-insert-macro

Markdown

Markdown is pretty easy to write in. Here’s a few keybindings that I find useful:

Keybinding	Function name
C-c C-a f	markdown-insert-footnote
C-c C-l	markdown-jump
C-c C-a l	markdown-insert-link

Git (Magit)

When loading magit, I’ve bound C-x g to magit-status which is the starting point to your git experience inside Emacs. Once you’re looking at the status of a repo, here are the most common commands:

• s stage selected file/hunk/region
• c open the commit popup, with details explaining commit options
• P open the push popup, with details explaining push options
• f open the fetch popup, with details explaining options
• F open the pull popup, with details explaining options
• ? opens a help popup

Further customization

In init-emacs.org I’ve pointed out a few options you may wish to customize, such as bibtex-complation-library-path (for keeping track of pdfs associated with articles in your bib file) and bibtex-completion-notes-path (for keeping track of notes associated with entries in your bib file). Customization is usually as easy as setting the value of a variable. For example, set up where you keep pdfs, you could put the following under the :config of use-package ivy-bibtex:

(setq bibtex-completion-library-path "~/Dropbox/reference-pdfs")

Finding customizations

You can check out everything that’s customizable for each mode via M-x customize-group and entering the group you want. Or, alternatively, do C-h v (“help variable”) and search for a variable you think might exist. So, if you’re annoyed that ESS asks you for a starting directory every time you start it, you could do C-h v ess dir which shows you that ess-ask-for-ess-directory is a variable. It’s documentation says that if it’s non-nil ESS asks for a directory. So if you don’t want that, you just need to set the value of that variable to nil in your init-emacs.org file. I’d do it under the :config part of use-package ess-site with something like this:

(setq ess-ask-for-ess-directory nil)

Other starter kits

I’m by no means the first person to write a starter kit. There are several others out there, all of which are awesome. Perhaps of most direct relevance here are:

• Kieran Healy’s starter kit, which is specifically aimed at social scientists working in markdown/R/latex/git. There are a few differences between this and that one:
  • I don’t include as many customizations. This is intentional - his probably works better out-of-the-box for many people, but I think that this one should be easier to understand and further customize.
  • His is focused on Macs whereas this starter kit supports Linux, Mac, and Windows OS’s (BSD should also work but has not been tested)
• Spacemacs is a community driven configuration. It is very powerful but super complicated - much more so than most people need. That said, if you’re used to vim keybindings, this is probably the way to go
• Doom is another vim-like config that you might prefer if you like vim keybindings. Currently ESS/R support is only in the develop branch, it’s due out in the 2.1 release.

Troubleshooting

Emacs is a computer program, and there are always problems with computer programs! I use a Linux distribution and so have tested this pretty thoroughly there. It should work fine. I have loaded it on Windows as well and it should work. I haven’t tested in on a Mac (don’t have access), but there’s no reason it shouldn’t work there just fine. If you run into trouble, read this section. If you still can’t get something to work, please open an issue on github.

Windows

Windows is… a tedious operating system. Emacs has a whole FAQ set up here that may help you find a solution to your problem.