Emacs Part 1: The Keyboard and Packages

This is the first part of a series in building an emacs configuration around the data science toolkit, which I introduced in another article. I won't be covering the absolute basics here, like how to download and install Emacs, but just my thoughts as I start building my configuration from a brand new ~/.emacs.d/init.el¹. In many ways, this is a notes-as-I-go type of article, and I may gloss over details I don't find important yet or would become obvious after a little Googling.

If this is your first exposure to Emacs, this is what it looks like when you download it and start it without configuring it at all:

At this point, the world is your oyster - they provide a few helpful links to get a new user started, but basically we can take this program and make it do whatever we want, including writing and building this website! While Emacs is a fairly feature-rich editor by itself, I know there are features it doesn't provide off the shelf that I want to include, especially:

1. Language server stuff - like pyright for Python editing
2. A git management UI
3. Intellisense-like code completion

That means we need to get comfortable with whatever plugin or package system emacs supports. My first impression exploring Reddit, package author sites, and github is that most Emacs-ers have an incredibly favorable view of throwing whatever kitchen sink you like into your configuration, as long as you feel happy.

This is a strikingly different attitude compared to (especially vanilla) Vim configuration advice. Typically when asking for advice in the Vim circles you'll first be greeted with "you aught to try this built-in capability first". There are also notably vocal members who will argue against using any plugin that doesn't serve some critical missing functionality of the editor. When dipping into the Emacs forums, quite to the contrary, I've seen members mention "I know person A does it like X because of Y, but I do W because Z", often from a place of understanding or empathy to a particular use case. One user even mentioned that they need vertical popup to assist with voice-powered coding tools, and hence will only consider auto-complete frameworks that work in that way for them. That level of community acceptance and support is encouraging to see, and Neovim has adopted a similar attitude to some extent, but is still somewhat nascent, especially with the recent Vim9/Lua debacle.

I'm including this section about "how to use your fingers" because it's something I desparately wish had been laid out for me when I was first starting Emacs. There are a lot of key combinations in Emacs that rely on consistent, easy access to the Ctrl and Alt (option on macOS) keys. What I was lacking was a guide along the lines of "use your left little finger for this modifier, followed by your thumb for this one." Starting out, some of the combinations looked impossibly slow to be useful, just because of the muscle memory I already built around using Ctrl and Alt. For instance, imagine seeing this keyboard shortcut for navigating up three lines in Emacs:

1. Ctrl + 3
2. Ctrl + p

At the time, I was used to hitting Ctrl+3 with my right little finger on the Ctrl in the lower right and left middle finger on the "3", and then using the left Ctrl for Ctrl+p. That seemed like a lot of wasted arm movement just to do what would normally be 3k in Vim. In reality, nearly every Emacs user has the "Ctrl" key just to the left of their little finger on the home row.² This is where most American keyboards place the "Caps Lock" key, which in my opinion is just dead useless. Regardless of whether you use something like Vim or Emacs, this is a good key to remap, and I do it on every workstation with one of these pieces of software:

• macOS: Karabiner Elements (Third party)
• Windows: PowerToys (included with Windows 10)
• Linux: On Ubuntu/Gnome it's usually as easy as Tweaks -> Keyboard & Mouse -> Additional Layout options
• QMK Firmware - when I'm on one of my fancy programmable keyboards

Given that remapping, the combination should work like this:

1. Left little finger holds down "Ctrl," using what is normally the "Caps Lock" key
2. Press "3" with left middle finger
3. Press "p" with right ring finger
4. Release "Ctrl"

I can perform this version just as fast as 3k in Vim - since the "Ctrl" and "3" can happen at the same time. Below I've listed my general "finger flow" to maintain tempo while using Emacs. For the rest of the article I'm going to use Emacs-style notation, which means C-x is "Ctrl" plus "x" at the same time, and M-x for "Alt" plus "x" at the same time. The M is short for "Meta", a vestigial artifact of Emacs' history as a screen terminal program, and a common point of befuddlement for young, unwary travelers like me.

• Left little finger for "Ctrl", left of "a" on American QWERTY keyboard in almost all cases
• Left thumb on "Meta" (Alt/option), just to the left of the spacebar for most cases
• Left little finger to use "Cmd" (Windows key, emacs calls this "super") just to the left of "Meta", when modifying a right-hand letter, i.e. ⌘-p
• Either right little finger or right thumb to use "Cmd" when I need a left-hand modified character, like ⌘-w, depending on the keyboard I'm using
• For C-x and C-c specifically, I have my right enter key bound to "Ctrl" on hold, "Enter" on tap, so that I can type the x and c characters as I normally would, without stretching my left little finger upwards and to the left at the same time. When I don't have the ability to program my Enter key this way, I'll hop between using the right Ctrl and modified Caps Lock key
• For M-x (that's "Alt" and "x" together, or "option" + "x" on a mac, which Emacs calls "Meta") specifically, I will usually use either my right thumb or right little finger on the Alt/option key, depending on the keyboard and how wide the spacebar is, because I find that more comfortable than crossing over on my left hand to hit both keys. Similarly, I find M-q, M-w, and M-z all easier by using both hands

Now that we've made it past the first hurdle of using the keyboard, we can actually open Emacs and start configuring it. The most radical departure from my experience in Vim/Neovim starts here, with the Easy Customize interactive system. Emacs leans heavily on its interactive components, backed by plain text and data - which was admittedly a pleasant discovery. VSCode rediscovered this type of system by providing an easy customization UI representing a swath of JSON configuration under the hood, which has proved immensely popular. By comparison, I would argue that the Emacs interface is downright hideous, but easier to grok.

By way of example, let's walk what it looks like to customize the color theme just via interactive commands. First, we hit M-x, Emacs' equivalent of the "Command Palette", if you're coming from something like VSCode or Jupyter, and enter customize-theme to get a menu that shows all the default color themes we could use. Another option, barring the use of M-x, is to use the menu bar and mouse just like we would in any other GUI program: "Options -> Customize Emacs -> Custom Themes" takes us to the same place.

Clicking the check box next to "tango-dark" and then clicking the "Save Theme Settings" results in a modified color theme that looks like this:

There are now two new things in your home directory:

1. A file called .emacs
2. A directory called .emacs.d/

Opening the former using "File -> Open File…" (which may require turning on a "Show Hidden Files" option, depending on your system) shows us this set of text:

(custom-set-variables
 ;; custom-set-variables was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 '(custom-enabled-themes '(tango-dark)))
(custom-set-faces
 ;; custom-set-faces was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 )

The code here is Emacs LISP - a programming language in its own right - and the main configuration language for the Emacs editor. Coming from Vim, where the only method of configuration is by manually editing your ~/.vimrc, this really blew my socks off. The implication here is that we can use interactive menus, backed by a proper programming language (not just JSON data), which can take effect right next to my hand-tuned configuration, and I'm free to modify it however I like later on. It is a bit cumbersome to have two folders dedicated to configuration, though, so the first thing I do here is "File -> Save As…" and write it to ~/.emacs.d/init.el, then delete the ~/.emacs file. Emacs will automatically detect this and load the correct file the next time we start it up.

elisp version      Kinda like
-------------      ----------
(foo)              foo()
(foo "bar")        foo("bar")
(foo "bar" 2)      foo("bar", 2)

;; ~/.emacs.d/init.el
;; Redirect custom so it doesn't edit this file
(setq custom-file "~/.emacs.d/custom.el")

;; Load the custom file
(when (file-exists-p custom-file)
  (load custom-file))

;; ~/.emacs.d/custom.el
;; --snip--
'(package-selected-packages
  '(vertico))
;; --snip--

;; ~/.emacs.d/init.el
;; Enable built-in package manager
(require 'package)

;; Redirect custom so it doesn't edit this file
(setq custom-file "~/.emacs.d/custom.el")

;; Load the custom file
(when (file-exists-p custom-file)
  (load custom-file))
;; At this point, package-selected-packages has been set by loading the custom-file

;; Remove any packages that are installed, but aren't listed in package-selected-packages
(package-autoremove)

;; Keep our registry up-to-date
(package-refresh-contents)

;; Install selected packages
(package-install-selected-packages)

;; ~/.emacs.d/init.el
;; --snip--
;; Keep our registry up-to-date
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-refresh-contents)
;; --snip--

(use-package tree-sitter
  :init (global-tree-sitter-mode)
  :hook (tree-sitter-after-on . tree-sitter-hl-mode)
  :config
  (use-package tree-sitter-hl)
  (use-package tree-sitter-langs)
  (use-package tree-sitter-debug)
  (use-package tree-sitter-query))

• 2022-08-19: Recommend against the MELPA-stable repository, after a bit of research