Falling down the Emacs rabbit hole

· geek · software · emacs ·

It has been about 18 months since I started using Spacemacs, and I am still constantly learning wondrous new things about it, and about Emacs more generally. I go through waves of tinkering and learning, but I find myself using Spacemacs for more and more things. I’ve had a recent tinkering bout — partly inspired by some helpful resources — so I thought it was probably worth documenting what I’ve done here for anyone interested, and so that I remind myself what I did when I inevitably forget a few months down the line! This is going to be quite a long article, so whether you are an Emacs fan, or just Emacs-curious, you might want to get a drink of your choice and settle back.

The first useful resource has been a series of videos by Eivind Fonn called Spacemacs ABC, in which he uses the which-key help that pops up in the modeline to work methodically through pretty much all the commands in Spacemacs. This — as it turns out — is a lot of commands. I haven’t worked my way through all of the videos yet, but even so I have learned some really useful commands that I didn’t know about, and also how to find help on commands and features more easily. It’s a great series, and I recommend dipping in to it every now and again to top up your knowledge. Another set of videos that I have found very helpful is a series on Org mode by Rainer König. He uses standard Emacs rather than Spacemacs, but the short videos are really helpful for introducing many of the features of Org mode in bite-sized chunks, from the basic stuff to much more advanced features.

Org mode and Pandoc

I still use Org mode every day, and for most of my writing that can be done in plain text. Even if I know that I will have to produce a Word document for colleagues, I often start with an Org document, using Pandoc to convert to Word. Sometimes I even continue that way, since you can now convert Word documents back to text sources (even incorporating Track Changes, which is magical). I can — in effect — treat the Word documents as read-only, and convert to and from my preferred writing environment, while still maintaining a socially acceptable format for my colleagues to use.

Recent versions of Spacemacs have included improvements to the org layer, and it now includes ox-pandoc by default. I have therefore been able to rework my layer a bit, and also move some of the configuration for Org mode from my .spacemacs file to a private org layer. Since I am still very unclear about how you should go about structuring layers, I started with a layer published by CestDiego and then edited it to cut out the stuff I didn’t understand or need, and move in my own customisations. That is working well on the whole, but I still cannot seem to get org-babel working properly. This has been an ongoing issue for me since before I started my recent round of tweaking. If I define the languages to be included in org-babel in the config files, I get an error on startup, but I can execute the same code manually after Spacemacs has started and it works fine. I’ll probably eventually work out how to fix this, but for now it doesn’t bother me too much.

I thought more carefully about which of ox-pandoc settings I wanted to apply to all files for a particular converter, and which I would need to specify on a per-file setting, and I have arranged my configuration accordingly. I use XeLaTeX as the engine by default for anything using the LaTeX or Beamer converters, and I’ve tweaked a nice Memoir-based template that was originally developed by Kieran Healy (combining parts of this and this). I ended up using the principle of the chapter styles and so on that he set up, but I started from scratch with the default Pandoc LaTeX template so that I could retain the ability to set various variables manually if I need to. This, combined with a Yasnippet automatically filling out the appropriate settings in the header of the Org file, means that I can very quickly produce a gorgeous looking PDF file for a document, but also easily adapt the style (for example, using a different reference format) by just changing one of the header settings in the Org document. I should also mention that Albert Krewinkel has done a fantastic job of improving the features available when converting from Org to other formats using Pandoc, and the process is much smoother now.


I think I knew when I started using Spacemacs that Emacs could render images and PDF files, but I had slightly dismissed it. Why, I wondered, would I want to view PDF files in Emacs when I have a perfectly good PDF viewer in Preview? I frequently take notes while viewing a PDF in another window, so I had already set up a keyboard macro using Keyboard Maestro that would (when you had a Preview window and an editor window side by side), automatically switch to the Preview window, scroll down (or up) a page, and then switch back to the editor. However, it was somewhat fragile, and if your windows got out of order, it failed.

I recently had to mark a large number of dissertations (in PDF format), and was using an Org file to take notes under a series of headings representing various elements that needed to be assessed, and I got curious about doc-view. I have to say, I love it, and wouldn’t go back to my old way of working. I was able to put Spacemacs full screen, split the window side-by-side, and have my notes on the left and the current PDF on the right. Even better, I found some handy code by Felix Ren-Chyan Chern which I adapted for Spacemacs’ page up and page down settings:

;; Reading a PDF while taking notes in another window (2 window setup)
;; Hit M-[/M-] to go up/down while keeping cursor in current window.
;; http://www.idryman.org/blog/2013/05/20/emacs-and-pdf/
(fset 'doc-prev "\C-xo\C-u\C-xo")
(fset 'doc-next "\C-xo\C-d\C-xo")
(global-set-key (kbd "M-[") 'doc-prev)
(global-set-key (kbd "M-]") 'doc-next)

This works beautifully: I can remain in my Org file, but page through the document I’m viewing on the right with Opt-[ and Opt-].


Dired is Emacs’ directory editor, and I had often come across it when opening directories on Emacs. However, I hadn’t really taken the time to get to know it and find out how best to use it. Like many of Emacs’ features, it is deceptively powerful and useful once you get to know it. For example, you can mark files interactively to operate on them (using a regular expression to select files if you want), and even enter an edit mode, where Dired acts like a normal buffer and you can edit file names directly. One reason that I found it awkward before was that it would spawn a new Dired buffer each time I entered a new directory, which cluttered up my buffer list. In trying to find out how to delete all the Dired files, I discovered how to select kinds of buffers in Helm, mark them all and then kill them all, which was very useful to know (hello rabbit hole!). I also came across code to prevent Dired from spawning new buffers in the first place, using find-alternate-file. Then, via Jason Blevins’ blog, I found an excellent tip for setting the z key in Dired to use the Mac open command to open the directory or file under the point with the default application (which would generally be Finder for directories). This is immensely handy for the few things that Emacs can’t handle easily, or just for locating a file to email to someone1. My dired customisations are below, and include a Spacemacs setting so that I can open Dired with Space od (nicely mnemonic: Space Open Dired). It’s possible something like this is already set up, but I couldn’t find it. You can, however, jump quickly to the directory of the current file by using Space fj.

;; Dired customisation
(setq dired-listing-switches "-alh")
(define-key dired-mode-map (kbd "RET") 'dired-find-alternate-file)
(define-key dired-mode-map (kbd "^") (lambda () (interactive) (find-alternate-file "..")))
  "od" 'dired)

;; Open files in dired mode using 'open'
;; http://jblevins.org/log/dired-open
(eval-after-load "dired"
      (define-key dired-mode-map (kbd "z")
        (lambda () (interactive)
          (let ((fn (dired-get-file-for-visit)))
            (start-process "default-app" nil "open" fn))))))


When I first started using Spacemacs, I continued to use iTerm to do most command-line stuff, but eventually I started playing around with shells within Emacs. You can continue to use terminal emulators and run zsh or whatever you are used to, but after reading an article on Eshell, I got curious about using that. Eshell is actually written in Emacs-Lisp and also acts like a REPL for running Lisp code. It re-writes most of the common commands that you might use in normal shells, so it feels very familiar. However, because it is written in Emacs-Lisp, it is much more tightly integrated with Emacs than other shells, so you can easily open files, open Dired (which I find easier than repeatedly using ls), and so on.

It has a lovely feature called Eshell smart display. When this is enabled, the cursor stays with the command you have just executed, rather than jumping down to the new (empty) command prompt. It’s a bit difficult to explain why this is so useful, but essentially, if you issue editing commands, you edit your previous command ready for you to re-execute it. If you type anything else, it jumps down to a fresh prompt. This means that you don’t have to keep invoking the command line history if you need to tweak a command. Also, if you give a command that produces a lot of output, you can immediately use Space or Backspace to page up and down the output, as if you had piped the command through less or a similar pager. As soon as you hit any other key, you are back at a new prompt again. I wish normal shells had this feature, as I’m always entering a command, realising that it produces too much output, and doing it again but piped through a pager. Eshell just magically does what you want the first time.

I’ve found that Eshell is more predictable and stable than any of the other terms in Emacs, so I’m now routinely using it, the same way that I used to open a terminal window in tmux. In fact, right now as I’m writing this, I’m editing the Markdown file in one window, I’ve got the CSS file open on the right (because I’ve been tweaking the CSS for code highlighting), and I’ve got a thin Eshell window on the bottom, running the Hugo server so that I can preview this article in a browser window. Once you’ve set your default shell to Eshell, popping open (and closing) a shell window like this in Spacemacs is as easy as typing Space '. Eshell doesn’t play well with interactive commands that redraw the screen (like top), but for the kinds of tasks I tend to do, it’s more than enough.


I’ve got a lot of different ways to use git, but I’ve tended to use Tower when I want to do something moderately complicated, or I want to see in detail what I’ve changed in the current commit. Magit may change that. It’s an extremely full featured git interface, which remains easy to use because it features extensive menus and hotkey guidance, a bit like Spacemacs. It is also very well integrated into Spacemacs, so you can get to all the functions by typing Space g as a prefix. I don’t use half of the features, but once you’ve got used to the flow from screen to screen, and the way that you can toggle diffs by just hitting tab while the cursor is over a filename in the list, you can fly though processes. I like the way that while it spawns windows so that you get lots of information, they disappear once you have entered your command, or you hit q in windows where you are viewing information interactively (like the git log window). Again, it makes the process of working with your files very seamless, as you don’t have to switch to another application to commit or push code. I’m using git a lot more at work for various projects, so this is becoming increasingly important to me.


Emacs also has a calculator. Of course it does — it is practically an operating system which happens to have an editor attached. It also has different kinds of calculator interfaces, depending on your needs, from a simple mode-line interface for quick calculations (the result gets put in the paste buffer automatically for pasting into your file), to a full bells-and-whistles mode that apparently gets pretty close to Mathematica for features. Again, I started out by wondering why I would need to use a calculator within Emacs when I’ve got calculator apps coming out of my ears, but gradually, app-by-app, Emacs takes over your life. Emacs calc-mode is pretty nifty, and I find myself using it more than is probably reasonable. And so it begins…down the Emacs rabbit hole we go!

Living with Spacemacs/Emacs

Emacs is a mighty beast. Using Spacemacs makes Emacs more accessible for newbie users like me, but also adds another layer of things to learn. However, in my opinion, taking time to learn about the tools you depend on is never wasted, and I am certainly much more efficient in my workflow than I have ever been. If it hadn’t been for Spacemacs and its deep integration of Vim within Emacs, I would never have tackled the Emacs beast. But then I would have missed out on the power and flexibility that it provides, and its ability to replace lots of other tools and provide an integrated, deeply customisable working environment. On the rare occasions when I write substantial quantities of text in other applications, I find myself constantly entering ‘dd’ ‘cas’ or ‘(’, as I try to delete a line, delete the current sentence and enter edit mode to write a new version, or move to the previous sentence. Writing in those kinds of environments feels utterly cumbersome. There’s nothing like the joyful, powerful feeling of flinging text around to rearrange it, jumping between chunks and fixing them as a new thought occurs to you, all without taking your hands of the keyboard, or your eyes off the screen. I love it.

  1. I don’t (yet) handle my email in Emacs, though it can do that very ably. ↩︎