emacs – the only guide you’ll ever need

I use emacs every day and for as much work as I can on a computer and have for about 9 years. It was not easy to learn, though, and I used it casually for about 8 years before starting to use it seriously and all the time in about 2002.

Learning was harder than I think it should have been – primarily because the main tutorial (invoked with C-h t) focuses on lesson after lesson of basic file and editing operations instead of trying to teach you just a couple very basic and core lessons about emacs itself. So, I attempt to present:

The only emacs tutorial you’ll ever need

Emacs does a lot and new users definitely needn’t try to understand all of it. I really ramped up dramatically faster in my learning curve once I discovered and mastered a very short list of basic functions that help explain the major interactions with the software.  Before this, I was very, very often feeling trapped by it and it convinced me (many times) to turn away (to vim, TextPad, WinEdit, notepad, and other software). Now I can’t imagine trying to use something else to get work done.

The short version: I believe that if you start by learning describe-function, describe-key (and where-is), apropos, modes (and describe-mode), and ctrl+g, you will ramp up on emacs much, much more quickly than if you do not.

  1. Every key press in emacs executes a function. Whether you press the “a” key or some key sequence involving the control (“C-“) or Meta (“M-“, usually by pressing ALT or the Escape key) keys, you are running some function. This is probably different from most software you normally work with.
  2. Every function has documentation. You can see this documentation by executing the function “describe-function” and typing the name of the function you want to get documentation on.
  3. Many functions can be invoked by name. You do this by pressing “M-x” and entering the function name in the minibuffer.  For example, if you type “M-x describe-function [ENTER]” emacs runs “describe-function” which asks you for a function name. Type “describe-function” and you will see the documentation on “describe-function”.  I said “many” and not “all” functions can be invoked by name – in the function’s definition it must be declared to be interactive for this to work. Emacs has a lot of non-interactive functions (e.g. basic lisp functions like car) which cannot be executed interactively.
  4. “describe-key” (and its close sibling “where-is”) can help you explore keymappings. I mentioned that when you press “a” it runs a function – to see what function that key sequence runs, type “M-x describe-key [ENTER] a”. This tells you pressing “a” executes “self-insert-command” and shows the documentation of self-insert-command (that it will “Insert the character you type.”). Similarly you could use “M-x describe-key [ENTER] M-x” to see that M-x is bound to execute-extended-command (which opens up the minibuffer and asks you for a function to run). Cool!  So let’s say that you know there is a function called “goto-line” which lets you jump to a specific line in a file.  You’re lazy, though, and don’t want to type that whole thing out whenever you want to use it.  “M-x goto-line” – so much typing!  Instead, you can type “M-x where-is [ENTER] goto-line [ENTER]” and emacs will tell you what keysequences goto-line is mapped to. In my setup, they are: M-g g, M-g M-g, <menu-bar> <edit> <goto> <go-to-line> – so I have three ways to get to it.  Another invocation of “where-is” and I learn that “describe-key” is bound to “C-h k” – so the quick way to do the first operation in this section (“what function is run when I press ‘a’?”) is: “C-h k a”.
  5. “apropos” can help you find (or remember) useful functions. Say you didn’t know that goto-line was the function to jump to a line in a file. If you type “M-x apropos [ENTER] goto” you’ll get a list of (interactive) functions that include “goto” in their name. Personally, I find this more useful to remind myself of a function I can’t quite remember than to find a function I don’t know at all, but it’s very useful. (short way: “C-h a goto”)
  6. Your major mode sets up a number of default behaviors about your interaction with emacs. All interactions take place in a single major mode and you can see this mode in the modeline it might be (“Lisp Interaction”, “Apropos”, “Shell” and others).  Depending on your mode, your keys will behave differently!  This can be very confusing to new emacs users.  For instance, when I press “C-h k <TAB>” (to inspect what the TAB key does) in Lisp Interaction mode it runs indent-for-tab-command (to indent some line for lisp programming), in Shell mode it runs comint-dynamic-complete (to try to tab-complete a function or file name), and in Apropos mode it runs forward-button (to navigate to the next linked entry in the apropos output).  “describe-mode” will tell you what mode you are in (and what minor modes are enabled) and what many of the major keybindings are for that mode. (short way: “C-h m”)
  7. Minor modes can be mixed in to add more customizations. Most of your keymap will be defined by the major mode you’re in, but there are some editing conveniences that can be put on top of this that may transcend any particular mode.  A pretty good example is “folding” – a behavior that lets you collapse large sections of a document and see a larger structure.
  8. Ctrl+g runs “keyboard-quit” You may find yourself locked in the minibuffer or with emacs trying to get you to complete some command you don’t understand – ctrl+g can frequently get you out of this.  (note: it’s not perfect – you might wind up in recursive edit but that’s another story).

These are the things I wish I knew before I started any of the tutorials.  The tutorials *are* good and the reference cards *are* handy, but I was frequently frustrated and confused why the keyboard didn’t react in the ways I wanted (I didn’t understand modes in general, least of all the one I was in), I didn’t understand how keys worked anyway (didn’t know about describe-key), didn’t know how to increase my proficiency once I started getting a little more comfortable (didn’t know about where-is or apropos), and didn’t know how to learn more about many of the functions (didn’t know about describe-function or apropos). Those are commands I still use every day when using emacs today.

Leave a Comment