wax banks

second-best since Cantor

Month: July, 2022

Some hints for the new or prospective Emacs user.

Emacs is enormously complex — but not complicated. There aren’t a lot of moving parts to learn about, but they interact in fantastically rich and complex ways, and it can be hard to know where to start.

I wish I’d had a ‘here are the standard components of a good Emacs setup’ guide when I started. There are distribution packages that handle such setup for you — Doom, Spacemacs, et al. — but if you actually want to be an expert Emacs user, you’re far better off getting comfortable with vanilla Emacs and then (if ever) switching to a prepackaged distro once you know what you want. The value of Emacs is lost when you hide its inner workings behind such ‘sugar.’

Emacs might be the most impressive single piece of software ever written for personal computing (not counting operating systems etc.). With great power comes great responsibility; here are some tips for absolute beginners, to help you claim them both.

My imagined reader is an interested non-programmer wondering about this weird and supposedly powerful tool. Experienced programmers should rely on other guides to get started, though newbies might learn something.

Learn about M-x

Start Emacs, then type Meta-x — on a Mac this should be Option-x, on Windows Alt-x. The cursor will move to a one-line text area (the ‘minibuffer’) at the bottom of the screen. This is a place to talk directly to Emacs. It awaits your input.

Type kill-emacs, hit Return, and congratulate yourself on a job well done.

Meta-X, abbreviated M-x, is the standard ‘invoke a command’ key combination. After invoking M-x, you type the name of a function — a small piece of computer code defined within Emacs — and hit Return. Emacs tries to run the code.

There’s a lot of functions available. Emacs exposes its guts to the user; that’s the source of its astounding power, the feeling of weird freedom it grants.

But don’t type M-x kill-emacs anymore — C-x C-c will do from now on.

Learn about C-g

Type M-x kill again, but don’t hit Return — we’ve changed our mind, we want to live!

Hit Ctrl-g (abbreviated C-g).

Nice work, you just canceled a command, or more precisely you just executed the keyboard-quit command.

C-g is bound, by default, to the universal ‘cancel and escape’ command in Emacs. Get used to it. (I’ve got that command remapped to the actual Escape key, for reasons.)

Swap Caps Lock and Control

Caps Lock is nigh useless and Emacs will wear out your Ctrl key real fast. Figure out how to swap them on your computer/keyboard, and enjoy knock-on benefits from consigning Caps Lock to the bin where it belongs. Better yet, sell your car and buy a ZSA Moonlander keyboard instead, then set up homerow modifiers. I’m not joking — the ergonomic benefits are huge, beyond even the major ergonomic upgrade from moving to a split/tented configuration. (No one with normal hands/arms should ever use a ‘normal’ keyboard again.)

Learn about online help

Hit C-h, then k. (In emacs documentation this is written ‘C-h k,’ get used to that nomenclature.) You’re now in help mode, specifically executing the describe-key function, and you are prompted to type a key command. Type M-x and look what pops up: the name of the function ‘bound’ to M-x, and a description of that function.

Now hit C-g, or hit Escape three times (these are basically equivalent). The popup help area is dismissed.

Emacs has extraordinarily rich help of this kind: describe-function and describe-face (as in ‘typeface’) and describe-bindings, but also an excellent built-in tutorial and a famous batch of very long manuals whose first editions date back several decades.

Knowing how to get help with and from Emacs will make the experience much much smoother.

Learn about your init files (like .emacs)

You’ll spend a lot of time tweaking your ‘init files’ later — e.g. your .emacs file in your home folder. What you need to know right now is this: they’re not just preference files. Your init files are themselves computer programs, executed line by line every time Emacs launches, written in a language called Emacs Lisp or elisp. To configure Emacs, you’ll write code — arbitrary code — and this is one of the most badass things about Emacs. Normal settings/preferences files specify adverbs, and the software sticks to its standard verbs; your init files let you provide the verbs directly.

See, Emacs is an umbrella for running other pieces of software. It’s like a word processor, but it’s even more like the operating system a word processor runs on.

There are good tutorials online and loads of sample init files to browse, as well as the excellent Emacs Manual.

Learn about buffers, windows, and frames

In Emacs, ‘everything is a buffer.’


  • What you call a ‘window,’ Emacs calls a ‘frame.’
  • What you’d call a ‘pane’ or equivalent — half of a split screen, say — Emacs calls a ‘window.’
  • And a buffer is an area containing text, sometimes — but not always — connected to a file, i.e. ‘visiting’ a file.

When you start up Emacs and get kicked to the *scratch* buffer, you see *scratch*, the minibuffer, and the modeline (which isn’t a buffer, actually; rather it’s a feature of the window it’s in).

When you open the calendar (M-x calendar), up comes a read-only calendar-mode buffer. In calendar-mode — a ‘major mode’ — pressing ‘o’ brings up a prompt to enter a new calendar year, i.e. ‘o’ is bound to a calendar-specific function in that major mode. (Hitting ‘q’ exits the calendar program…but doesn’t kill the buffer, per se. Don’t worry about it.)

Each buffer has a current major-mode, and any number of minor-modes (including global ones which apply to all buffers). Understanding how these work and interact is essential to navigating Emacs, and a huge help when it comes to learning commands and keystrokes.

Learn about modes

Way beyond the scope of this document, but you need to be able to answer a few questions:

  • What major-mode is currently active?
  • What minor-modes is currently active?
  • What’re the keymaps for these modes?
  • How do I change these things?
  • How and when do modes get invoked?

Thinking of a ‘mode’ as a ‘syntax’ will get you a lot of the way there, but not all the way.

Print a movement cheatsheet

I like this one. Getting around Emacs buffers can be weird, and the commands you’re probably used to probably don’t work ‘right.’ Learn the Emacs commands, even if they seem weird or stupid. Weird doesn’t matter if you’re fast and accurate. You should put in the time to master moving quickly around the buffer.

Learn how to execute elisp code anywhere

In the *scratch* buffer that opens when you launch Emacs, type (+ 2 3) and, with the cursor just after the closing parenthesis, type C-x C-e. Check out the minibuffer: it should say ‘5’ and you just executed a bit of Lisp code, which should be easy to decipher even if you’ve never seen it before.

Remember how your init files are computer programs? And now you’ve just run a very short program in the middle of a random textfile. Understand: Emacs gives you access to its own guts, all the time, no matter what you’re doing at the time.

You’ve never had this degree of control over a piece of software before, this level of introspection available. You interact with the program by altering it… If you’re thinking it through, that should be a head trip, the kind that’s good for you.

OK, so much for the ultra-simple stuff. Now for the ‘…but how do I make Emacs more normal?’-type advice.

Select a package manager

Emacs loads extensions or ‘packages’ on launch. You download a package (M-x package-install, then specify name), and load it up. Doing this manually is a pain in the ass — and it makes your setup/config much less portable, since you can sit down at a new computer with the same init files and not have the packages you need to make them work.

Use the use-package or straight.el package-management tools. I use and recommend the former.

Get a narrowing-completion framework

Now we go into the weeds just a little bit.

Every Emacs user relies on a tool like Ido (interactive-do), Ivy, Avy, Helm, et al.: programs that let you narrow a list of choices, select quickly and smoothly, and do smart things with your selection. For instance, you wanna be able to type M-x packinst and have Emacs figure out that you mean package-install — this is ‘fuzzy finding’ and the vanilla alternative is terrible. When you run find-file (C-x C-f, i.e. ‘open’), factory-fresh Emacs behaves like the command line, where you’re expected to type exactly what you mean and get only tab-completion to save trouble. But look up Ivy and Helm online and see what else is possible.

Same with searching in a buffer. Emacs’s built-in incremental search function is good — try C-s * in a buffer full of text — but a jump-to-match tool like *avy is insanely good. Once you’ve tried it, you won’t want to go back to the mundane world.

Get in-buffer completion

Distinct from list-completion is a tool like Company (‘complete anything’), which autosuggests and does code completion. When I’m typing in my personal wiki, if I pause mid-word for a fraction of a second, company’ll pop up an ‘are you trying to link to this file?’ suggestion; I hit return to get a properly formatted link right there, boom. You need a tool in this class, which leapfrogs the whole pack of ‘minimalist text editors’ which so fascinate dabblers and dilettantes. (If you’re after that hipster typing experience, pick a classy font and turn on writeroom-mode or darkroom-mode or olivetti-mode.)

Pick a nice theme

Stock Emacs doesn’t look like anything, unless ‘old’ is a look. But it’s got loads of themes available, some (e.g. Zenburn, Monokai, Gruvbox) really very nice. There are even packages to enable live theme previews. Add commands to your init file to download and enable the theme you like, then…

Sync your init files

Dropbox, Github, Syncthing, whatever. (Github might be best because no overhead: anywhere you have a command line and an Internet connection, you have your files.) Pick a service, sync your init files between machines, and carry your Emacs everywhere you go. You don’t realize how empowering this is until you do it, then you can’t not do it.

Learn about keymaps

There is a logic to Emacs key commands, and there is an implicit keystroke ‘composition’ happening behind the scenes — learn about mode-specific keymaps and the subtle mnemonics will start to reveal themselves. When I’m in markdown-mode, say, C-c C-s is a prefix to nearly 30 markup commands, e.g. C-c C-s b for boldface. The logic is sane: C-c for user/mode commands, C-s for insssert(!), b for bold. On an ergonomic keyboard this is quick and, crucially, discoverable.

And you should install which-key ASAP, to prompt you when you’re not sure of a command.

Emacs’s commands lack the tight focus of vim’s bespoke fingertip-interface, but so does everything; vim is a hyperoptimized, narrowly focused tool, Emacs is a cosmos. Yet once you get that there’s an implicit modality to Emacs’s keyboard UI, you can start tailoring individual shortcuts to your preferences without having to worry about colliding with some other definition. And of course, C-h k is your friend.

Tighten the modeline

Use diminish/delight to remove unwanted minor-modes from your modeline, grab a useful theme (I use spaceline), and get the program working (and looking) exactly the way you want it.

Get markdown-mode or whatever

The target audience for this article probably writes in Markdown a fair amount. Jason Blevins’s markdown-mode is really good; set it up to auto-engage when you open a .md/.mdown file, get comfy with the shortcuts, and you’re just about ready for md-roam (q.v. ‘org-mode’ below)…

Consider evil-mode

One of Emacs’s dirty open secrets is that its keybindings are borderline insane. Even something as simple as ‘C-g to cancel’ — seriously, not just Escape? You have to engage your stupid pinky finger hundreds of extra times a day? (Assuming Ctrl is in its usual place, that is…)

I use Escape in place of C-g, but that doesn’t help with ugliness like ‘M-} to go down a paragraph.’ And I use a frankly expensive Moonlander keyboard that gives me homerow modifiers — but I only have so many fingers and don’t love stretching for chords all the time.

Consider evil-mode, which is not just the best but the best possible vim emulator in the business: a full-on modal editor with all of vim’s famously terse, ergonomic, and composable key commands, atop Emacs’s fantastic extensibility and power (and using elisp for extensions, instead of the widely disliked vimscript). Imagine floating on vim’s interface, and being able to dive into Emacs whenever you like.

If you can get comfortable with modal editing (where hitting Escape pops you out of typing mode into navigation/command mode, freeing up your basic single-stroke alphanumeric keys for stuff other than typing), then evil-mode is one of the hidden killer apps for Emacs — a ‘better vim’ built in to the editor that’s supposed to be vim’s, I dunno, nemesis or something.

Notice some minor tools

Try M-x calendar and M-x calculator. Pretty nifty, eh? And each is just a buffer, meaning all the ways of manipulating a text buffer’s contents are available to you inside these ‘minor’ tools.

Consider org-mode

Holy shit, org-mode.

Along with evil-mode, org-mode is Emacs’s secret weapon — but where evil-mode is there to bridge the vim/Emacs gap to make Emacs a better pure text editor, org-mode is a whole ecosystem of unique software tools. And org-mode is not just Emacs-native but basically Emacs-only. At its heart, it’s a task-manager, outliner, and personal productivity tool; it does things like automatically gather to-do items from every file in a project into an agenda, that kind of thing. It is, and yes I know this sounds crazy, easily the best tool of its kind — get your setup Just Right and it’s the last productivity software you’ll ever need. And it’s deeply integrated into Emacs, down to the bones. Capture a to-do item from inside any buffer. Insert a link to an org outline item (node) into any file, along with dynamic to-do status tracking. Track overall project status in futureproof portable plaintext using tools that automate all the clerical work. Export to a million formats. (People write entire scholarly books in org-mode w/bibtex on the backend and spit out gorgeous LaTeX with a keystroke.)

I use an org extension called org-roam (which began as a Roam Research emulator) to maintain a slowly growing ‘zettelkasten’ or ‘personal knowledge management’ setup. It’s great — but org alone is insanely powerful.1 Indeed, if you’re on the fence about whether to try Emacs at all, org might be what pushes you over to this side. (It’s one of the biggest Emacs/vim differentiators, certainly.)

(Mac users: there are tools to connect org-mode to programs like Drafts, to move you toward ‘ubiquitous capture.’)

Check out magit

Magit is the best frontend for git. There’s just no serious competition in GUI-land or at the command line. You think I’m being hyperbolic, but for God’s sake go have a look.

Check out GNU hyperbole

This one you’ll have to see for yourself: an all-purpose ‘turn textual features into buttons’ machine. You don’t need this software — I don’t use it — but it’s one of the most outlandish achievements in the Emacs sphere, just a terribly impressive and useful piece of software. It’ll change how you think about text editors, which is sort of the point of this whole exercise.

Quality of life

From here you can start making quality-of-life improvements of varying scope:

  • dogears to supplement Emacs’s persistent bookmarks with quick per-session bookmarks
  • marginalia or equivalent (e.g. ivy-rich) to display useful information during interactions w/Emacs
  • org-roam or deft for managing libraries of notes
  • flyspell (with aspell behind it) for strong spellchecking, and flyspell-correct for the right interface for your completion framework
  • avy, because it’s a different paradigm from the ‘standard’ helm/ivy approach and it’ll help wean you off those pesky non-ergonomic arrow keys, which are killing you
  • crux, though you’ll soon end up replacing all its handy constituent functions with features of other packages
  • dirvish for a way better file-nav experience, and either dirvish-side or neotree or equivalent for a folder-hierarchy sidebar
  • all-the-icons for all the icons
  • org-bullets and org-ql and oh there’s so damned much you can do with org-mode
  • yasnippet, which brings snippets over from textmate/sublimetext and makes them way more powerful (you can execute elisp code in a yasnippet)
  • projectile, obviously, for usefully restricting search to a project and integrating nicely with loads of other tools
  • visual-regexp-steroids, if you want realtime previews of regular expression substitutions plus freedom from Emacs’s indescribably irritating regex syntax (all those escaped parentheses!)

Put simply: your first days with Emacs will be interesting but difficult. But one day you’ll find yourself doing something that’s simply impossible with literally any other text editor ever written, and something down deep will awaken — it’s not a text editor, it’s a Lisp runtime that edits text — and you’ll spend the next however many years dealing with, and figuring out for yourself how to take advantage of, that knowledge.

  1. I’m switching away from org-roam for non-org reasons, beyond the scope of this article. 

M-x midlife-mode.

(written about a month ago)

A few months ago I made an abortive attempt to learn vim. Well, one hits midlife and wants to shake things up, it’s natural. But one mustn’t go to extremes.

I quickly realized that while I admire vim’s ergonomically sound modal editing approach — wherein you type awhile in Insert mode, hit Escape to remap all the keys to navigation/manipulation commands, then hit I to return to typing — and while it’s handy to command a tool that’s preinstalled on every unix machine, vim doesn’t feel to me like a step-change in capability. I already have a perfectly good standard-issue text editor (Sublime Text), and my layer-centric keyboard already picks up some of the ergonomic advantages of vim’s modal approach.

So lately I’ve been learning emacs instead. I haven’t used it since college, when I learned Scheme using Edwin (an emacs clone).

I was/am tempted by org-mode, though I have my task- and knowledge-management tools (Things 3, lots of Markdown docs, etc.) and don’t particularly feel like switching (yet?). But after a couple of days I’ve experienced something profound, and suddenly feel like I grok emacs (and realize I never have before).

Here’s the secret, I think: LISP everywhere.

The first time you extend the most basic functioning of the editor by writing/evaluating a line of LISP in whatever textfile you’re working in — the moment you understand what LISP’s ‘”data” is code’ paradigm means not only for configuring but for operating this program in the moment — you realize how limited your idea of a text editor has theretofore been. To my eye, vim is an interesting/impressive computer program, like Sublime Text or VSCode or Xcode, and emacs is a philosophy (as well as an operating system, as the semiserious line goes, lacking only a decent text editor).

(Others seem to experience the same phenomenon from, as it were, the opposite direction, seeing vim as intentionally conceptually unified and emacs as a horrifying mishmash. My response is tentative, and its first draft is: ‘That’s what I said.’)

Today I added a simple markdown-mode-hook to my .emacs file, setting font colours for bold/italic text irrespective of theme (I’m a disgusting ape). Writing LISP to dynamically set the face attributes on load feels fundamentally different from changing a value in a static settings doc; instead of tossing nouns into the verb-machine, you’re altering the machine itself. This is such a profound change that talking about it is embarrassing — so different from the norm that it sounds like conspiracism or religious blather. Maybe real programmers already interact with their tools like this; I’m an utter novice again, could be I’m independently ‘discovering’ the wheel. But this is giving me a vertiginous feeling that I recognize from, say, the first time I created a site in Rails. Categories being overwritten entirely.

Ugh, please ignore me.

Initial zettelkasten thoughts.

  • It’s not as complicated as newcomers think, nor as interesting as adherents think. But it’s a little complicated, and interesting.
  • The method has little to do with ‘taking notes’ and much to do with ‘outboard cognition.’
  • The self-published semischolarly book on the subject is a good read: Sönke Ahrens, How to Take Smart Notes. Ahrens is a true believer, which could be intolerable, but he’s also a scholar and teacher, and hammers home the central point that the slip-box is part of a comprehensive creative-intellectual workflow — i.e. his book looks like self-help but doesn’t read or work that way.
  • The ‘digital garden’ is only alive in traversal, i.e. when you are thinking it through. Meaning you need to be revisiting your notes regularly; the output of the zettelkasten method is the zettelkasten, parts of which you can gather and revise for publication.
  • My misunderstanding, a common one, was that the zettelkasten method is about storing notes. That is incorrect, badly and essentially so. You store notes in a box. But a brain isn’t a box, it’s a network of machinery. It constantly acts, it churns. The ‘second brain’ metaphor is precise: the associations formed between notes themselves constitute a kind of thought. This is non-neural cognition, of a sort. Think of it as a unique inorganic living thing, a cognitive supplement: a thinking-machine.
  • In other words, you don’t store material inside it to think with; you think inside it.
  • The zettelkasten argues implicitly. Nodes aren’t thoughts; the connections between them are thoughts. Following connections is following a kind of argument. This is nothing like, say, Wikipedia, where each node is a discrete info-drop.
  • All of this is to say, the slip-box (theoretically) makes you a better writer and thinker by making writing into thinking, and making everything writing.
  • This quasi-mystical gobbledygook is characteristic of the zettelkasten community, which has produced almost nothing of value but a library of blogposts about zettelkasten. (Where are the interesting writers/thinkers using this method?)
  • Org-roam is a good implementation whose main weaknesses are (1) you gotta be in Emacs to use it, which you almost certainly aren’t, and (2) viewing and following connections is a frustrating experience at times. It wants shorter entries in org syntax.
  • Obsidian is a good implementation geared toward the same people nearly every such product is geared toward — productivity bloggers. It wants longer entries in Markdown syntax.
  • Denote isn’t strictly a zettelkasten implementation at all, which is a big reason for its excellence: all it wants to be is a great note-taking system for Emacs, using long rich filenames as primary sort/search tools (i.e. no database reliance, so slower but better integrated w/Emacs at large). It’s a new package, but sanely designed and rationally opinionated and therefore not just immediately useful but immediately helpful. It wants whatever you’ve got, form/sizewise.
  • If you pay money for zettelkasten software you’re a fool.

It’s nice to be pleased with a paragraph of your own writing.

If Sandover is ultimately an artistic failure — debatable but let’s humour the boring consensus for a moment — in what sense, by what standard, does it fail? What is Merrill supposed to be doing? Litcrit rules are dumb and dangerous but the time for circumspection is past: in Sandover, Merrill fails in an attempt to become transparent, to socialize his (and Jackson’s) vision. A long literary work ‘teaches you how to read it’ when its early movements provide the tools for accessing the more difficult later material: an API or access-language. Sandover‘s later movements, though beautiful, are a taxing read because they sacrifice clarity for purity.


Excerpt from mss. in progress –wa.

Yeats’s ‘lonely impulse of delight’ — the mundane-mystic vision at the heart of his Irish airman’s honest testament — comes back to me unbidden several times a year. It’s one of the few ‘adult’ poems I’ve memorized, and it’s hard for me to recite it without breaking down. OK, now how’s this for mundane: the aerial chase that brings the third Matrix movie to its climax, with Trinity’s flying-craft breaking through eternal oilsmoke night, vouchsafed her (our) first glimpse of the unscarred sky only to plunge to cruel death which in turn frees her blind lover-brother to save both the human and the machine worlds, is forever intertwined in my stupid head with Yeats’s ‘tumult in the clouds.’ ‘I balanced all, brought all to mind’: peace and equipoise, slow and life and quiet amidst machine-death. Trinity looks out at the old world (light from 93 million miles away, memory of faraway minutes ago) and whispers, ‘Beautiful.’ She flies toward grace.

Perhaps it’s an anglicization of an Oirish name.

The trouble is, there are lots of people like Elon Musk — smart but less than they think, and stupid enough to think that they have a clear idea of what ‘first principles’ means in any given context they might stumble into.

I periodically delete my Twitter account.

It’s not a big deal, it’s just that Twitter is bad for humans and I periodically remember that I am one.

At the moment I’m listening to Valium Aggelein while working from home, like so many losers. Everything’s adequate. See you later.