Tag Archives: emacs

Emacs and lisp


The Emacs text editor uses lisp as an extension language. This article will attempt to explain enough lisp to do basic emacs customization, to someone who knows imperative programming languages.

Evaluating lisp

Lisp consists of balanced pairs of parantheses, filled with tokens, separated by space, eg. like this:

(somefun1 1 2 3 "four")
(somefun2 5 6)

The flow of a lisp program is to start from the top, and evaluate the balanced parantheses and their contents. When doing this, lisp expects the first item in the list to either be a function (actually the name of a function (or actually a symbol bound to a function (but now it is time to stop digressing and nest up the parantheses and continue))), or what’s called “a special form”.

Evaluating functions

For now, let’s assume that the first items are all functions. Then the example above, would be to just invoke “somefun1” with three integer arguments and one string argument, then invoke “somefun2” with two integer arguments.

Ie. basically, the same as this C fragment, except with the parantheses surrounding the name of the function, and no semicolon to terminate each statement:

somefun(1, 2, 3, "four");
somefun(5, 6);

But a more interesting, or typical, lisp example, would be something like this:

(somefun1 (+ 0 1) (+ 1 1) (+ 1 1 1) (concat "f" "o" "u" "r"))
(somefun2 (- 11 6) (- 11 5))

What happens when lisp starts evaluating the first line, is that it will evaluate each of the balanced parantheses, before it eventually serves them up as arguments to “somefun1”.

Then lisp will move on to the next line and do the same thing there, and continue with this, until it reaches the end of input.

Evaluating “special forms”

Evaluating a special form differs from evaluating a function in the way the arguments are evaluated.

Examples of special forms, are the flow control constructs of lisp, eg. the “if” special form:

(if (= 2 2)
    (message "If test was true!")
  (message "If test was false!"))

When lisp encouters an “if” special clause, it will start by evaluating the first argument.

If the result of the first arguent is other than nil, the second argument will be evaluated. If the there are more arguments to “if”, they will not be evaluated.

If the result of the first argument is nil, the third, and following arguments to “if” will be evaluated (this is the “else” part of the if clause). In this case, the second argument to if will not be evaluated.

Trying out lisp

In emacs, go to the scratch buffer. This can be done with `C-x b *sc TAB RET’.

Type the following text into the buffer:

(message "Hello minibuffer!")

Place the cursor at the end of the line, and press `C-j’. Two things will happen:

  1. The minibuffer will show the text “Hello minibuffer!” (without the quotes)
  2. The line below the line you typed in will get the text “Hello minibuffer!” (this time with the quotes)

The `C-j’ command will evaluate the lisp expression that ends on the same line as the cursor, and the evaluation result will be printed on the next line.

The evaluation result is useful when debugging an expression, such as the test argument to an “if” special form.

If you don’t wish to move the cursor to the end of the clause being tested, you can instead press `C-M-x’, which will evaluate the outermost clause, under the cursor.

Using `C-M-x’ won’t output the evaluation result to the scratch buffer

Setting variables

In the .emacs file you can set variables that affect how emacs operates. On unix-ish systems, the .emacs file resides in the home directory. On windows systems the default is to look for the file in the “%USERPROFILE%AppDataRoaming” directory (unless the HOME environment variable, in which case emacs looks for it in “%HOME%”).

One of my oldest settings is one that stops emacs from saving “~” backup files:

(setq make-backup-files nil)

In today’s emacs one can set a simple settings like this interactively, using the customize mechanism.

The most important thing to be able to do, is to set various configuration variables. Today this can be done interactively for many variable using the “customize” mechanism.

But it’s still useful to be able to know how to set variables in lisp, eg. for setting variables differently depending of the type of file loaded, the version of emacs, or the OS one is running on.

To set variables, use the special form “setq”. Type the following into the scratch buffer, and evaluate it:

(setq a-variable-used-as-an-argument t)

Now a-variable-used-as-an-argument is a variable, and you can use it in lisp code. The value is t.

Defining functions

Functions are defined with the “defun” special form. An example, is:

(defun somefun1  (firstarg secondarg)
  "This is a function to do something.
If firstarg is non-nil it will output that firstarg was true.
If firstarg is nil it will output that firstarg was false.
The secondarg argument isn't used for anyting at all"
  (if firstarg
      (message "Firstarg was true!")
    (message "Firstarg was false!")))

First try `C-h f somefun1 RET’. Emacs will say “[No Match]” when RET is pressed.

Then move to the scratch buffer and paste in the code of the example, and use `C-j’ or `C-M-x’ to evaluate the defun clause.

Then try `C-h f somefun1 RET’ again. This time the emacs window will split in two and the lower half will show:

somefun1 is a Lisp function.

(somefun1 firstarg secondarg)

This is a function to do something.
If firstarg is non-nil it will output that firstarg was true.
If firstarg is nil it will output that firstarg was false.
The secondarg argument isn't used for anyting at all


To try using the function, paste the following into the scratch buffer, and evaluate it:


This will cause the lisp debugger to pop up, saying that the function has two methods, but is called with none.

Add some arguments to the function call and evaluate it again:

(somefun1 nil "Required but unused")

The minibuffer will show “Firstarg was false!”. Now try putting different values as the first argument. All values, other than nil, will result in “Firstarg was true!” being written to the minibuffer.


Many variables used by language modes are “buffer local”. This is so that eg. c-mode can use different indentation settings on two separate source files, to accomodate the different indentation/formatting used on them.

This means that if you set the variable when starting up emacs, the buffer version of the variable may not get the setting.

To make it possible to customize this, and other things, many emacs format specific modes provides “hooks”.

A hook is a list of functions, and emacs will run all functions in that list when doing a particular operation. Typically there are hooks for loading and saving files.

In summary

In the same way as the two preceeding articles, this article describes the subset of lisp and emacs lisp, that I use on a regular basis. Lisp by itself could probably be a lifetime study. I have for instance skipped mentioning macros, which are another important construct in lisp. Macros allow programmers to create constructs that behaves similar to special forms. Macros can e.g. be used to create new control structures (the macro “when” is such a control structure. It is nicer syntactically than the special form “if”).

Suggested reading is the Emacs Lisp Reference Manual and An Introduction to Programming in Emacs Lisp. In addition to reading them on the net, you can read them in the builtin manual reader of emacs (`C-h i m elisp RET’ and `C-h i m emacs lisp TAB RET’).

Using org-mode


This article is a quick walkthrough of org-mode basics. Or rather: those org-mode basics I have personal experience with.

Some bullet points on org-mode:

  • org-mode has been part of GNU Emacs since v. 22
  • the development version of org-mode resides at http://orgmode.org/
  • it is based on the emacs outline mode, which allows for easy tree structure navigation, and editing
  • It has easy export to HTML, PDF, TeX, and DocBook
  • I use it as:
    • An organizer for work (it’s big on TODO lists)
    • A time tracker
    • A habit tracker
    • A meeting scheduler and note taker
    • A work notebook
    • A document editor for short memos and similar documents

The first thing this article will do, is to create a sample org file, and then try some operations on that file

Getting a more up-to-date version of org-mode

This section tells how to get the latest version of org-mode.

The download information is here: http://orgmode.org/index.html#sec-2

For installation on linux, see here.

For installation on windows, first download the org-7.8.09.zip file, to Downloads, and unpack it to Downloads, so that the directory becomes Downloadsorg-7.8.09

Then open the file AppDataRoaming.emacs from your user home directory, and add the following:

;; Configure 7.8.09 version of org-mode if present
(let ((org-mode-directory
       (expand-file-name "~/Downloads/org-7.8.09")))
  (when (file-directory-p org-mode-directory)
    ;; Add info and load paths to the git version of org-mode
    (add-to-list 'load-path (concat org-mode-directory "/lisp"))
    (let ((org-mode-info-dir (concat org-mode-directory "/doc")))
      (if (boundp 'Info-directory-list)
          (add-to-list 'Info-directory-list org-mode-info-dir)
        (setq Info-directory-list (append
                                   (list org-mode-info-dir)
    ;; Do org-mode setup
    (require 'org-install)))

Start emacs and do `C-x d’ and in the prompt the specify the Download/org-7.7/lisp/ directory. Press `t’ to mark all .el files and then `B’ to byte compile the files. Press `y’ on the question of whether it should byte compile all files.

Open an org file, and it should open in the 7.7 version of org.

Setting some sensible configuration

First do `M-x load-library RET org-clock RET’ (to load `org-clock-into-drawer’).

Customize these values to non-default settings:

  • `org-cycle-include-plain-lists’ – set to “As children of outline headings”
  • `org-clock-into-drawer’ – In the value menu, choose other, and give the string “CLOCK” (without the quotes)

To customize a variable, do `M-x customize-variable RET’ then give the name of the variable (use SPC and/or TAB to expand the variable name). In the windows that shows up, select the right value from the value menu, then “set for current session” (`C-c C-c’), then “save for for future sessions” (`C-x C-s’), then finally `q’ to exit the customization.

Creating an org-mode file

Load a new file called “notes.org” (`C-x C-f notes.org RET’).

Give the file the following content (just paste it into emacs from here):

-*- mode: org; coding: utf-8 -*-
* Meetings
** A silly meeting
   SCHEDULED: <2011-12-07 Wed 13:30>
** Another silly meeting
   SCHEDULED: <2011-12-23 Fri 14:00>
* Howtos
* Tasks
** TODO Explain org-mode [1/2]
 - [X] Explain basic emacs editing
 - [ ] Explain org-mode itself
** TODO Write a memo
* Documents
** A simple memo
*** Introduction
Blah, blah, and blah.
*** A little about this
About this I have little to say.  One could have a list:
 - A list could have an item
 - Another item could be in the list
 - List levels can be nested
   - A nested element
   - Another nested element
 - Back on the level.

A new paragraph.  You can have code fragments in org-mode documents:
#+begin_src c
  int main(int argc, char* argv[])
      printf("Hello world!n");
*** Some more about that
A new section, some more text.  Lists can be numbered:
 1. A numbered item
 2. Another numbered item
 3. Even numbered items can be nested
    1. a nested item
    2. another nested item
 4. An item on the top level

Look, here's another new paragraph.
*** Concluding words
In conclusion we have to say that blah, and blah, and blah, and so
forth, and even more.

Some final words are these.  The last line, even.

After pasting in, if the mini buffer still says “Fundamental”, do `M-x revert-buffer RET y e s RET’.

Basic org-mode commands

These are some of the most basic org-mode commands. Try them out on the document created in the previous section.

  • `TAB’ – expand and close tree nodes
  • `M-RET’ – create new node on the same level as the node under the cursor
  • `C-c C-e 1 h’ – export node under cursor, and its children as an HTML document (try this on eg. the sample memo)
  • `M-uparrow’ – Move node under cursor, and its children up one level
  • `M-downarrow’ – Move node under cursor, and its children down one level
  • `M-rightarrow’ – Move node under cursor down one level in the tree
  • `M-leftarrow’ – Move node under cursor up one level in the tree
  • `M-shift-rightarrow’ – Move node under cursor, and its children, down one level in the tree
  • `M-shift-leftarrow’ – Move node under cursor, and its children, up one level in the tree

Using TODO items

Do `C-c / t’. This will open all TODO items and the tree items directly above them.

Move the cursor to a line containing a text starting the red text TODO. Then give the command `C-t’ and the text switches to a green DONE. Do another `C-t’ and the text goes away. Another `C-t’, and the red TODO is back.

To create a new TODO item: move the cursor to the end of a TODO line, and the start of a TODO line, and do `M-S-RET’.

Using checklists

TODO items can be hierarchical. This makes the parent TODO item depend on its children (it won’t be automatically be marked DONE when they are complete, but it can’t be marked DONE until all of its children are DONE).

However, I prefer a more lightweight mechanism, called checklists. Mosly because I think they are visually clearer than nested TODO items. The first thing I do when starting to think about a task, is to create checklist items for the things I want to do.

Empty checklists are also handy to store away as HOWTOs in a different place of the org file (the sample document has a HOWTO node on the top level).

To try out checklists, open the “Explain org-mode” TODO item.

Move to the “Explain basic emacs editing” line and do `C-c C-c’. The checked checkbox will become unchecked and “1/2” on the TODO line will change to “0/2”. Then do `C-c C-c’ again, and see that the checkbox is checked and “0/2” changes back to “1/2”.

Move to the end of the “Explain org-mode itself” line, and do `M-S-RET’. A new checkbox will be created at the end, and the “1/2” on the TODO line itself, will change to “1/3”.

Do `M-rightarrow’ with the cursor on the bottommost checkbox. The checkbox is indented and the “1/3” on the TODO line goes back to “1/2”. Give the text “Explain TODO items” (without the quotes), then do `M-S-RET’ to get a new checkbox. After the new checkbox, give the text “Explain text export” (without the quotes).

Do `C-c C-c’ on one of the two new checkbox items and see that the parent changes from empty to “-“. Do `C-c C-c’ on the other checkbox item, and observe that the parent checkbox becomes checked and that “1/2” on the TODO line, changes to “2/2”.

There are some downsides to using checkboxes over nested TODO items:

  • Time stamped notes (`C-c C-z’) end up directly under the TODO item, rather than under the checkbox
  • Time tracking will only happen on the TODO item

Tracking time

Move the cursor to a TODO item, and do `C-c C-x C-i’ (“clock in”). This starts the clock running on that item.

To stop the clock running, you can:

  • `C-c C-x C-o’ to “clock out”
  • “clock in” on a different item
  • `C-c C-t’ to toggle the TODO item with DONE

The status line will show the sum of the time used for the clocked in item.

You can clock into all tree items, not just TODO items. So you can eg. leave a TODO item to clock into a meeting.

You can use the `C-c C-x C-d’ to display the sum of time used for all subtrees.

You can modify the starting time by moving the cursor into the start timestamp and

Including error messages and code fragments

I use org-mode first to create TODO tasks, and meetings, and then later to take notes when doing the tasks or meetings.

Especially when taking notes in TODO tasks, I need to include command line commands, error messages, and fragments of error logs.

The way to do that, is to use something like this:

  This is a line from an error log
  This is another line from an error log

You can either type



manually, or you can do `< e TAB’.

To insert the example put the cursor on the blank line between the begin_example and the end_example lines, type a single character, eg `e’, and then `C-” (“ctrl single quote”).

In the buffer that shows up, delete the `e’ character (the purpose of this character, is to avoid org putting in a lot of spaces that you have to delete), then paste in your command line command, or log file file fragment, or error message, and then do another `C-” to end the edit session.

If what you want to store is a programming language fragment, rather than an error message, you should use “begin_src” instead of “begin_example”.

To create a “begin_src” do `< s TAB’, then type in the name of the language you want to include, eg. `java’ (the supported language syntactically closest one to C#), and then arrow down to the blank line between “begin_src” and “end_src”, and type in a character, eg. `s’ and then `C-” to edit the code fragment.

The edit buffer for the fragment will be in the language specific mode, used for that programming language.

More: read the manual

There is much more to org-mode than this. To find out more, read the org manual: http://orgmode.org/org.html

You can also read the org manual from inside emacs: just do `C-h i m org RET’.

Once you’re in the manual, just do `q’ to return to where you came from.

A fresh `C-h i’ will take you back to the manual, to the place where you left it.

You can navigate the manual by moving the cursor over a marked hyperlink and pressing `RET’ (or just click on the link using the mouse).

Some other manual (or “info reader”) commands:

  • `l’ – takes you back to the previous page
  • `n’ – takes you to the next chapter/section on the same level
  • `p’ – takes to back to the previous chapter/section on the same level
  • `u’ – takes you up one level in the document structure
  • `i’ – do an index search for a term
  • `s’ – search the manual itself for a string

Very basic emacs usage


Emacs is a very powerful and flexible text editor.

This is a very quick walk-through of essential emacs commands, based on my own experience of the commands I use most frequently.

I’m giving the key shortcuts, because those are the ones I use. But running in a GUI, you can use mouse navigation for such things as switching windows, and there are menu items for many of the commands.

I thought that this list would be short, but once I started writing I thinking about new stuff that I should include. Eventually I had to cut it down to what I really think are the basics.

I won’t spend any time on the flexibility of emacs, but will mention it in the section titled “Commands and key bindings”


Keypress sequences will be represented like these examples `C-x C-f’ (pronounced “control ex control eff”), `M-w’ (pronounced “meta double you”).


  • The sequence is delimited by a single back quote ` at the start, and a single quote ‘ at the end
  • Spaces in the command sequence are just separators. If pressing the space bar is part of the command sequence, it will be represented by SPC, e.g. `C-SPC’
  • `C-‘ means: hold the Ctrl key pressed while pressing and releasing the key connected to C with the hyphen
  • `M-‘ means: hold the “meta” key pressed while pressing and releasing the key connected to C with the hyphen. On PC keyboards the “meta” key is most commonly the “Alt” key
  • `RET’ in a command sequence means pressing the Return (or Enter) key
  • `TAB’ means press the tabulator key

Commands and key bindings

The actual commands in emacs are all lisp functions. The keyboard key combinations you press to run the command, are known as the “key binding” of the command.

If a command’s regular key binding has been masked for some reason, you can run the command with `M-x command RET’ where “command” is the command’s lisp function name.

Emacs allows replacing the key bindings for all commands with your own, and for a new emacs user it may be tempting to replace the default emacs key bindings with something more familiar. However, I recommend against replacing the default key bindings, because:

  1. different emacs modes often have a command set patterned on the base command set, and they are easier to remember for that reason
  2. if you come to a emacs installation that does not have your customizations you may not be able to use it

Exiting emacs

To quit emacs, do `C-x C-c’.

If running emacs with a GUI, you can also go to the File menu, and select quit.

Note that `C-x C-c’ is quite easy to hit by accident. It’s possible to make gnus query for whether it should quit or not, by customizing the lisp variable confirm-kill-emacs.

To modify the variable, do `C-h v confirm-kill-emacs RET’. The editing screen will split. Do `C-x o’ to move to the lower half of the edit area, move the underlined word “customize” and press RET. In the form that appears select the “Value Menu” button, and then choose “Ask with yes-or-no-p”. Then select “Set for current session”, then select “Save for future sessions”, then select “Exit”.

Getting help

The Help menu have lots of stuff. There’s an online tutorial that is worth following. All help commands are available through `C-h’ followed by a key.

I use the following help commands on a regular basis:

  • `C-h i’ to get the online manual
  • `C-h b’ to find the current key bindings
  • `C-h f’ to find the documentation for a lisp function (eg. a command),
  • `C-h v’ to find the documentation for a lisp variable

Note that for both `C-h f’ and `C-h v’ TAB and SPC can be used to autp expand the function or variable name.

Also note that many variable documentations have the text “This variable can be customized” in it. Move the cursor to the word “customized” and press RET. This will take you to a form where you can change the variable and persist the changes.

Loading and saving files

When starting emacs in a GUI environment, you will see:

  • A menu bar at the top
  • A toolbar below the menu bar
  • A big window with a blurb-looking text
  • A line with a different background color and some text and numbers
  • A white area at the bottom (known as “the mini buffer”). This is where you will be prompted for file names, and give search strings

To load a file into emacs, press the keys `C-x C-f’.

The minibuffer will present a prompt for the file name. It will suggest a path based on the current working directory. You can edit that path whereever you want to go, and the possibilities for the paths can be expanded by pressing SPC or TAB. SPC means “expand to the first separator character” (e.g. “/” or “.”). TAB means “expand as far as possible”.

To save the file type `C-x C-s’.

To save to a new file name, type `C-x C-w’.

All of these commands are available under the File menu, when running emacs in a GUI.

You can edit multiple files into emacs. To move between files, either use `C-x C-b’ to get a list of buffers, or `C-x b’ (no ctrl key for the b), and use TAB or SPC to expand the name of the loaded file you want to move to.

The `C-x C-b’ command will split the emacs window in two, vertically. Use `C-x o’ to jump to the lower half, and then arrow keys to navigate to the file you want to go to, and then `C-x 1′ to let it take the entire editing area.

You can also cycle through the loaded files with the commands `C-x C-right’ and `C-x C-left’ (“right” and “left” meaning the right and left arrow keys).

All of these commands are available in the Buffers menu

Editing multiple files

You can load as many files as you like (well… there’s a limit, but I’ve never reached it) into emacs at the same time.

To switch between files, use `C-x b’ (Note: no ctrl key for the `b’) and write the name of the file you want to go to (not the full path, just the local file name). You can use TAB and SPC to auto-expand the file name.

To see all files loaded in emacs give the command `C-x C-b’ (this time use ctrl for the b as well). The text editing window will split in two with the loaded files listed in the lower half of the screen.

To get to a loaded file, use `C-x o’ to switch the cursor over to the lower half, then cursor to the file you want to look at, and press RET.

Now the lower half will show the file you selected, but the top half still show again.txt. To make the new file use all of the editing area, press `C-x 1′ (“control ex one”).

There are many similar commands to split and close part of the editing area. I won’t get into them here. The manual has more.

Navigating in emacs

The normal arrow keys work as expected. So does page up and page down. The Home key will take you to the start of the line, and the End key will take you to the end of the line.

In addition you can navigate with Ctrl keys: `C-p’ is the same as arrow-up (p for “previous”), `C-n’ is the same as arrow-down (d for “down”), `C-b’ is the same as arrow-left (b for “back”), and `C-f’ is the same as arrow-right (f for “forward”).

Two of these commands have “meta” siblings: `M-f’ which forwards the cursor over the next word, and `M-b’ which takes the cursor over the previous word.

In addition there are `C-M-f’ (“control meta eff”) which takes the cursor over the next clause. Whatever the clause is depends on the type of file in the current buffer. In an XML buffer that would be an element. There’s also `C-M-b’ which moves a clause backwards.

The page-up and page-down keys also have ctrl/meta keys. `C-v’ is page down, and `M-v’ is page up.

Ctrl key equivalents for Home and End are `C-a’ and ‘C-e’.

Searching and replacing

To start searching in the current file, give the command `C-s’, then start typing the word you are searching for. The search is incremental so the more you type the more it will match. The cursor will move to the match.

When you have found a match, you can:

  1. Press `C-s’ to go to the next match
  2. Press `RET’ to stop the search at the current match
  3. Press `ESC’ to abort the search and return the cursor to where you were before starting the search

If you do `C-M-s’ instead of `C-s’ (ie. hold down both the ctrl and Alt keys, when pressing and releasing s), the incremental search will be a regular expression search, instead of just a plain search.

Another powerful search method is occur. Type `M-s o’ and the minibuffer will prompt you for a regular expression. After giving a regular expression and typing RET, the editing area will split in half, the lower half showing all matches. To go to a match do `C-x o’ to move to the lower half, use the up and down arrow keys to move to a match, and then press RET.

To search and replace, use the command `M-%’. You will be prompted in the minibuffer for search and replace texts. When being prompted, you can use the up and down arrow keys to select earlier search and replace texts.

The command `C-M-%’ is a regular expression search and replace, and adds complexity and power to the search and replace, but otherwise behaves the same as the plain text search and replace.

Cutting and pasting

To mark the area that is to be copied or pasted, press `C-SPC’ at the start of the area, and then move the cursor the other end. The area is now selected (in a GUI, it will show up as selected).

If you want to copy the marked region, use `M-w’, if you want to cut the marked region (“kill the region” in emacs terminology) use `C-w’.

Then move the cursor to where you want to paste it (“yank it”, in emacs terminology), and press `C-y’.

If you immediately (ie. without moving the cursor) press `M-y’ the yanked (ie. “pasted”) region will be replaced with the previously copied or cut region. By pressing `M-y’ again you will get the copy/paste preceeding it. You can continue pressing `M-y’ until you’re back to the last copied/cut region, and then continue past that again for a new cycle.

This is what emacs calls “cycling the kill ring”.

A very useful way of deleting lines is using `C-k’. This command will kill the rest of the line from the cursor point. If you continue to press `C-k’ the killed lines will be added to the most recent entry in the kill ring, rather than appear as new entries.

If you want to delete the next 50 lines you can do it with `C-u 5 0 C-k’.

`C-u’ is known as “the universal argument prefix”. It can be applied to many emacs commands, typically to give them a numerical argument.

Useful variables to set

There are some variables that are useful to set to values other than the default.

For all of them, do `C-h v variable-name RET’ then select the underlined word “customize” in the variable’s documentation, select the “Value Menu” in the form that appears, and set the appropriate value. Then select “Set for current session”, then select “Save for future sessions”, then select “Exit”.

The variables are:

  • `confirm-kill-emacs’ set to `yes-or-no-p’ (emacs will query yes/no on exit)
  • `split-width-threshold’ set to `nil’ (emacs will split windows horizontally)
  • `x-select-enable-clipboard’ set to `t’ (copy/paste will work from emacs to other programs)