Latest Update: Removed PlannerLove – the site is sadly departed, and the domain has been bought by some domain squatters.

Sacha is currently writing the book on Emacs. When it comes out, it would seem rude for me to not buy a copy and read it. And she’s a small powerhouse of infectious enthusiasm, which will drag me back to Emacs. So, I’m giving up early and going back now. I know when I’m beaten. I’d just got myself nicely settled as a Vim user, too…

---

Recently, I’ve been trying out a new way of doing GTD, and it seems pretty good to me. In the end, it was Emacs I couldn’t cope with using, but if you get on with Emacs, this could be for you. Let’s start with a disclaimer this time, though…

• This is one for the geeks.

It’s all based around using the Emacs text editor, which isn’t the easiest thing around to use, even just to edit a text file. It balances a couple of elisp programs on top of that, too, which let you do all sorts of clever things, using nothing but plain text. If you’re geek enough, though, and the idea of keeping everything in plain text appeals to you, this is one fast GTD system…

I should probably add another mini-disclaimer here to point out that I’m more of a wannabe geek than a real geek, so don’t think you have to be able to poo in C code, or reprogram your George Formby grill to pick it’s heat settings up as an XML file from your fridge. You need to be able to hack at text files, though, and not be too put off at reading manuals and learning a little elisp.

The System

Just so you can decide if it’s worth your while continuing, let’s start with a bit about the end result if you set up everything described in this article…

• You’ll be living in Emacs – all of your organizing will be done in Emacs.
• Plain text files will be used for storing all of your data. You could even edit the files with other programs, but you’d lose some of the automated stuff that PlannerMode provides – like duplicating tasks to a day page, a project page and a context page.
• Platform independent – you won’t have much problem if you decide to switch later from Windows to Linux or MacOS – they’ll both run Gnu Emacs and should be fine with all the other bits too. I’ve not actually tried any of this on other OSses, but it’s likely that most of the developers of the apps concerned aren’t running Windows.
• Create tasks in Emacs, by doing Ctrl-c then Ctrl-t. This will give you a series of little prompts for what, when, and projects/contexts.
• Daily Planner pages – every day has a corresponding page, listing all the tasks for that day, along with a section for scheduled things and a section for notes.

You can also get some idea of how the system will look in practice from eclair‘s screenshots, linked from near the bottom of this article.

Emacs

It’s all based on emacs, so you have to get that up and running first. There’s two options for this – Gnu Emacs, and XEmacs. Gnu Emacs seems to be used by more people, so there’s a bit more documentation around, and things are generally better tested with it, so that’s my choice. XEmacs integrates better with Windows, and has a nice simple installer, which is a bit of a help, but when you’re trying to get something running that you’re not familliar with, you probably want to go with whatever’s been tried by the most people. If you already use XEmacs, all this stuff should work just fine, but if you don’t use any Emacs at all, I’d go with the Gnu for now.

• Update: I’ve been using XEmacs more recently, and PlannerMulti, the add-on that makes GTD possible with Planner, doesn’t work as it stands with the newest version of XEmacs. It can be fixed by editing PlannerMulti’s code a little (thanks, Neilen!), but it might be another reason to go with the Gnu unless you have a particular liking for XEmacs. If you do carry out the linked fix, it’s the changes in the diff listed at the bottom of the post that worked for me. Entering tasks works slightly differently afterwards – instead of entering all of the contexts or projects you want to attach the task to with spaces between them, enter one at a time, and when you’re done, enter ‘nil’ (will usually be the default after you’ve entered the first one anyway). This may make more sense once you’ve read further on down, but it only applies if you decide to go with XEmacs and fix PlannerMulti yourself anyway.

Although Emacs is available for Linux and MacOS, I’m going to be assuming I’m talking to Windows users here. Hopefully most of it will be quite understandable for others too – most Linux users probably already have Emacs (or they use Vi and now they think I’m evil).

Getting

You can download Gnu Emacs from here – it’s the ‘emacs-21.3-bin-i386.tar.gz’ file you want (13Mb).

Installing

You need to unzip the file first, but it’s not actually a zip file – it’s a ‘.tar.gz’. If you’ve dealt with much Unix stuff in the past, you’ll probably be familiar with these already, but if not, they’re a tiny bit odd. It’s actually a .gz file, which contains a .tar file, which then contains the files you want. A decent unzipping program will handle these pretty easily, but you may need to open the .gz file, then open the .tar file inside it to get to the juicy bits upon which we wish to feast. If you don’t have any preferred unzipping software for this, 7-Zip does the job quite nicely, and it’s free. If you install that, just double-click the .tar.gz file, then double-click the .tar file/folder in the window that opens. In there, you’ll see the actual Emacs folder that we’re after- you can drag it from there to where you want it.

Once you’ve got to the Emacs folder, you need to copy it somewhere so we can run it. Although it should work ok pretty much anywhere, it’s really happiest somewhere without any long filenames – ideally, rename the folder to just “emacs”, and drop it in the root of your C: drive.

Under the “emacs” folder is a folder called “bin”. In there, there’s a program called “addpm.exe”. Run this, and you’ll get a nice icon for Emacs added to your Start menu.

Because of its Unix roots, Emacs will tend to refer to things relative to “~” – the Unix way of referring to your home directory. This isn’t set under Windows, and Emacs seems to assume it means the root of C:. Although this will work ok, it’s a bit inconvenient, and can mean a whole lot of messy files and folders all over the place. It’s a good idea to change this before we start. Right-click on My Computer, and select Properties. On the Advanced tab, click the button for Environment Variables. Add a new User variable, called “HOME”, with the value set to the folder you want to act as Emacs’ home. Personally, I put this under…

C:\Documents and Settings\pigpogm\My Documents\home\

…and just created a “home” folder in My Documents. This keeps it easy to get to, without cluttering up the root of C: any more than we already have.

Warning: Changing (or setting) the value of ‘HOME’ won’t affect many Windows programs, but you might find it upsets some. The only program on my system that was upset by it was The GIMP, which wanted to use the new HOME folder for it’s .gimp folder and font cache. When I started it and it started wanting to set up a new user, I just cancelled, and copied the .gimp and font cache files from where they were (under the docs and settings\pigpogm folder) to the newly created home folder. It then started again fine.

Setting the HOME variable isn’t needed to make things work, but if you don’t do it, don’t get all upset when Emacs does a poo all over your nice clean C: drive.

Learning

Emacs is not easy to learn. Even just being able to open and close files, and edit a bit of text is kind of tricky. Gnu Emacs does give you a menu in Windows, which helps, but to get the best out of it, you need to learn to use the keyboard for as much as possible. The best way to get started is probably to run the tutorial from the help menu. That will teach you most of the basics of editing, but you’ll need to spend a couple of hours going through it, at least.

PlannerMode

Modes

Emacs is always running in a mode. The main mode it runs in at any time is a Major Mode – which can also have any number of Minor Modes. Minor modes just change little things, like turning on and off font colouring, or changing how tabs are handled. Major Modes can change a lot more, like hiding some characters, making text display differently, or pretty much anything else. Many functions of Emacs can act differently depending on the mode it’s in. When nothing else is specified, it’s normally in Fundamental Mode. If it’s not, and you want to get back to normal, just switch to it by entering “M-x fundamental-mode” (and if that means nothing to you, you need to work through the tutorial).

PlannerMode is another mode. Planner, though, is based on another optional mode called Muse.

Muse

If you’re familiar with the idea of a wiki, Muse implements wiki-like functionality in text files.

Even if you’re not familiar with a wiki, that’s still what it does, it just doesn’t help you as an explanation

A few extra options for formatting are enabled, like beginning a line with a star and a space to make a heading, and anything in double square brackets is turned into a link to a file with that name. So, if you type the text “Write Article on PlannerMode [: UK, US]” in a file in Muse Mode, the square brackets will become hidden, and the text will become a link. When you move into the linked text and hit enter, Emacs will open a file called “Write Article on PlannerMode”, in the same folder as the file you were editing.

If the file doesn’t exist, it creates it. The upshot of all this is that you can create new pages very quickly and easily, just by mentioning them elsewhere.

Muse can do other things too, like taking all the files in a project, and publishing them in some other format – like a PDF file or a web site – but the wiki-like functionality is what PlannerMode makes use of. Once it’s working, you can pretty much ignore Muse if you like – Planner will use it quietly in the background.

Getting Muse

Get muse from this page on the Emacs Wiki – I followed the link to the releases, and grabbed muse-3.02.93.zip.

You should go there to get Muse, to make sure you get the most recent release. In case there are problems getting it from there in future, though, I’ve attached the version I used to this article – there should be a link to it near the bottom of the page.

Setting Up Muse

To make Muse work, first you need to unzip the file you downloaded for it, and stick the muse folder from inside it somewhere (I renamed it from muse- to just “muse”). I put mine under the home folder we created earlier, in a folder called elisp (‘elisp’ is the language used for Emacs extensions). So, the folder for the .el files that make up Muse is “~/elisp/muse/lisp/”. ‘~’ is home, and the actual .el files are in a subfolder of the Muse folder called ‘lisp’. So, to make it work, we need to add a line to our .emacs file (the script that Emacs runs at startup). The .emacs file is in your home folder. At this point, you need to be able to edit files and save them again in Emacs without breaking anything. Edit the file “~/.emacs”. Add a line to the beginning that says…

• (add-to-list ‘load-path “~/elisp/muse/lisp/”)

This tells Emacs to look for extensions in that folder too. We could probably copy the lisp files to somewhere else that’s already in the load-path, if we wanted to, but it seems neater to keep them in their own folder. Anyway, this is what the documentation I found said, and it worked, so I’m not going to play with it.

You shouldn’t need to do anything else for Muse – we don’t need to make it load at startup, because we’ll let Planner do that for us.

Planner

Planner adds to the already nice bits done by Muse, and turns Emacs into a speedy plain text organiser.

Getting Planner

Now you need to download a copy of Planner – it’s available from the Emacs Wiki. Again, I visited the releases page, and I grabbed planner-3.41.zip.

(As with Muse, the version I used should be attached at the bottom of this page, but it’s only there in case of disappearing files – you’d be better off getting to most recent release from the real source.

Setting Up Planner

Very similar to Muse. Stick the ‘planner’ folder (rename all those version numbers away) in a folder under your elisp folder, then add a line just after the one for loading Muse…

• (add-to-list ‘load-path “~/elisp/planner/”)

Planner doesn’t use a lisp subfolder, so that should do the job. We need planner to load itself at startup, though, so we also need to add another line to our .emacs, after all the add-to-list bits. Make a couple of blank lines to space things out a bit, and if you want to add comments, do it on extra lines, and begin them with two semi-colons (so you could add a line at the very top that says “;; Set the Load Paths”, for example). Now add another line…

• (require ‘planner)

This tells Emacs that it has to actually load Planner (if I’ve understood this stuff correctly – do let me know if I’m wrong – I just know it works like this .

To be able to do GTD with it, we need one more thing – the extension that Sacha made for us that lets us use multiple ‘projects’ with one task. Without that, we won’t be able to use projects and contexts, so we wouldn’t be able to do GTD. Time for another line, after the previous one…

• (require ‘planner-multi)

Planner-Multi is in the folder with Planner, so Emacs already knows where to get it from.

This is probably a good time to create the “Plans” folder under your home folder – PlannerMode won’t start cleanly without it.

At this point, it really should be working, but it wasn’t for me. I’d have a try at this point, in case things work more easily for you – later versions of the files may fix this problem. Close and reopen Emacs, and do “M-x plan”. If planner starts up without errors, and gives you your “* Tasks”, etc screen, you’re good to go.

That didn’t happen for me, and the error tells you to look in the Planner manual. The readme tells you the wrong location for the manual, but I found the bits I needed to change on this page of the manual, on the current maintainer’s site. Once I’d added the lines listed there to my .emacs file, Planner started up ok.

Just in case the page vanishes (it’s not responding at the time of writing), here are the lines I added…

(setq planner-project “WikiPlanner”)

(setq muse-project-alist ‘((“WikiPlanner” (“~/Plans” :default “TaskPool” :major-mode planner-mode :visit-link planner-visit-link)

(:base “planner-xhtml” :path “~/www/Plans”))))

You should now be able to ‘M-x Plan’ successfully.

Using Planner

Planner is another Major Mode for Emacs, but you run it by typing “M-x plan” – this will always start PlannerMode, and bring up today’s page – if you’re already in a Planner page, it just switches to today.

When first run, it opens up today’s plan page – every day gets its own page, with three sections – Tasks, Schedule, and Notes.

You can just fill in the Schedule section yourself, in whatever way you like.

The notes section can be used the same way, but makes a little more sense if you follow a few conventions (start each note with “.#n“, where n is the number of the note, and number them upwards, creating newer notes at the top).

The Tasks section is where the magic of PlannerMode happens.

Tasks

Although the tasks section is just text, you can cause problems if you edit too much by hand – Planner provides shortcut keys and menu options for creating and modifying tasks.

PlannerMulti

PlannerMode has one limitation that makes it of limited use for GTD – you can only attach a task to a single project. The problem is that projects are also the only method available to implement contexts – so a task could be attached to a context or a project, but not both.

Fortunately, Sacha has hacked a way around this – PlannerMulti. It’s an add-on to PlannerMode that allows you to enter multiple ‘projects’ for each task. For GTD use, you can use it to attach a task to both a project and a context. If you followed through the ‘Setting Up Planner’ part above, you’ve already got this installed and working.

GTD

If you don’t already know about GTD, you’ll probably want to read my introduction before we go much further. It’s a way of organising all the stuff you have to do. You probably know about it, though, if you’ve got this far down.

Working the System

Open today’s Planner page…

• M-x plan

Create a new Task…

• C-c, C-t
• Enter the task description (“Look up Emacs on Wikipedia”)
• Choose a date…
  • Today: Enter – (the entry will keep moving forward if you don’t complete it, so you can treat this as can do, not must do, if you like.)
  • Tomorrow, etc: +1, +2, etc.
  • On the 14th of this month: 14
  • On Date: Type the date.
  • Undated: nil – (might well be a well-used one for GTD people – you actually type the word “nil”, then hit enter.)
• ‘Page’ is both Project and Context in GTD terms. Separate with spaces, so your projects and contexts can’t contain spaces. Examples…
  • SalesReport @Work-Computer
  • ServicingCar @Calls

Mark a task complete…

• Highlight the task (move the cursor into it).
• C-c, C-x
• Planner marks it as complete here and on any other pages on which it’s listed.

Viewing a Context – there’s a couple of ways…

• Find a task that’s in that context, put the cursor on the context name (should be a link) and hit enter.
• Open the context’s file – should be wherever your planner files are, usually “~/Plans/”, then the file is called whatever your context is called. So the @Work context is probably a file called “~/Plans/@Work”.

Working it Further

There’s lots more options – rescheduling tasks, modifying the projects they’re connected to, editing the title, marking as delegated, pending, in progress, cancelled, etc, etc. Rather than go through all the options here, though, you can find them all for yourself. Once you’re on a Planner page, there is a Planner menu – have a browse through it. It lists the shortcut keys next to many of the items. Experiment with what the options do.

To keep your data safe whilst you’re playing and learning, just keep backing up the Plans folder. The easiest way is probably to right click on it, Send To, Compressed Folder. When the .zip file appears (Plans.zip), rename it (maybe ‘Plans 2006-05-25.zip’, for example), and keep those copies somewhere safe. If things go horribly wrong, you can always bring the whole folder back to before you broke it.

Other Resources

Sacha

Sacha didn’t originally create PlannerMode, and doesn’t actually maintain it any more, but a lot of the work on the current version, including lots of the stuff needed to make it work with GTD, were done by her. You can find out more on her PlannerMode page – in the blog that she writes and updates directly through Emacs. She’s quite a geek, and creative too (she’s one of the writers behind D*I*Y Planner), which is a great combination.

Clair Ching

Clair’s old site has some pages with lots of good screenshots to show you what PlannerMode actually looks like in real world use. If you’re still debating if it’s worth the effort, check them out…

• Planner Newbie
• Screenshots
• More Screenshots

She had a new blog with more Emacs goodness.

Woodnotes Guide to Emacs for Writers

OK, so it’s intended to be for writers specifically, but this guide from Randall Wood (hey, his first name is my last name) is one of the best introductions to Emacs around for us Windows users. He explains a lot of the terminology that can otherwise be a shock to the system – like a window being called a frame, and paste being called yank.

(Thanks to Clair for the link.)

Genehack

More of a productivity-side view than geek-side, this is another good article on how PlannerMode can work in reality…

• PlannerMode at Genehack

Related

GTD and Productivity

There are a few articles in our Productivity section, but the most popular ones are…

• The PigPog Method – doing GTD without a project list, one next action at a time.
• PigPogPDA – not really a GTD system as such, but a simplified system using a Moleskine notebook.
• GTD’s Dirty Secrets – what GTD doesn’t help with.

Text Editors

• Text Editors
• Text Editors for Writers