Org-mode

A Tool for Notes, Authoring and Project Planning

by Charles Olsen

I recently discovered a tool that can help you organize just about anything you're doing. I use it now to help me write podcasts, articles and stories. I've also seen demos where it's used for project planning. This powerful tool is called Org-mode.

Org-mode is a program that runs within Emacs. Emacs is a text editor that was developed in the 1970's by Richard Stallman. I had been vaguely aware of Emacs, but I never had a reason to use it. After all, how often do you really need a text editor? And when I did need one, I already had it. In a Gnome desktop I would use gedit, in a KDE desktop I would use kate. Problem solved.

Then I went to the Linux Workshop here at HAL-PC, and one of the guys there talked about how he ran his business and his life using Org-mode. At the next meeting, I met his wife -- who was using Org-mode to write fiction stories. And both of them spoke in detail -- and with great enthusiasm -- about how Org-mode was the most effective tool they had found for these tasks.

Since I'm interested both in organizing software and in writing fiction, I was very interested in Org-mode. I started using it right away to write the script for my podcast (mintCast, at http://mintcast.org.) And it really did make it easier.

Modes

Emacs is an extensible, customizable text editor. It includes an interpreter for Emacs Lisp, which is a version of the Lisp programming language that has extensions for text editing. And you can do some amazing things with this.

I've heard it said that some people think of Emacs as an operating system, and there's a lot of truth in that. You can develop entire applications that run within Emacs. A lot of people use it to write program code. Other existing programs allow you to use Emacs as an email client, a newsgroup reader, and to play games.

In Emacs, these programs are called "Modes." Modes can be simple things that perform one minor function, or can be entire applications.

Org is a mode for Emacs that was written by Carsten Dominik. The web site, which is orgmode.org, describes it as: "an Emacs Mode for Notes, Project Planning, and Authoring.

Usually when I talk about software, I emphasize how easy it is to get started and use. Org-mode is not quite so easy to get started. This is not a program where you just click File > New and start using it. You really need to invest some time in learning it.

Fortunately, there are a lot of tutorials available. When you go to the web site, you'll see a link on the left labeled "Tutorials." That brings you to another link that you can click to find a page full of links to tutorials and screencasts. There are some great tutorials available.

And you don't have to learn everything at once. You can learn new capabilities as you need them. I started by using Org to organize my writing. I'm now writing the podcasts in Org, and I've started converting some of fiction to Org.

Text

Org stores everything in a text file. Just pure text. I can imagine that some of you are rolling your eyes at that. Who uses text any more?

But that's actually part of the beauty of Org-mode. Any program can read and write text. If I got mad and decided that Org sucks, and Linux sucks, and that I'm going to switch to Windows Vista and do all my writing with Microsoft Office -- I could just copy my Org files over and open them in Word 2007. Or OpenOffice. Or even notepad. Almost any program will be able to open these files.

And this is important to me. Not that I expect to go insane and switch back to the pain of Windows, but more than once in the past I've used a program that was discontinued, maybe because the company went out of business. Of course the program didn't stop working at point, but it would no longer be updated, wouldn't receive any more security updates. So I needed to get my data out of it. If there wasn't an export function, that meant copying and pasting information – sometimes one record at a time. But text is the universal language for software. I'll always be able to read my files.

Keystrokes

Org-mode was created before the mouse was invented, so all commands can be given with keystroke combinations. The good news is, if you're a touch typist you can do everything without ever taking your hands off the keyboard.

The bad news is, the keystrokes are going to seem weird and unintuitive. For example, to open an existing file or create a new file, the command is Ctrl-X Ctrl-F.

A lot of commands begin with Ctrl-C or Ctrl-X -- the keys you're used to using for Copy and Cut. There are also a lot of keystrokes that use the Meta key. You may ask, what is the Meta key? Well, that varies depending on the OS. For those of us using Linux, it's the Alt key. But not all OS's have an Alt key, so in some cases the Meta key is the Escape key. So all the instructions you find will refer to the Meta key, and you have to remember to translate that to the Alt key.

I hope that's not turning you away from trying Org. Most of the functions are available on the menu, so you can use the mouse to activate them. But it's really worth learning a few of the key commands. And there's also a reference card on the Org web site that gives a summary of the Org commands and keystrokes.

So, what's the advantage to using Org? What do you have to gain by using it?

In this article I'm going to talk about organizing documents that you're creating. This can be any kind of document -- a letter, an article, a short story, a novel, a manual -- even a podcast.

You activate Org-mode by opening or creating a file with the extension .ORG. For my podcast file, I pressed Ctrl-X Ctrl-F, navigated to the folder where I wanted to store it, and entered the file name mintcast.org. Now I have an empty Org file.

Org is a super outliner. Outlines help you with structure, and are a great way to organize large documents. Or even small documents. You can work with varying levels of detail, creating headings and subheadings. You can start with a high-level overview, then create subheadings to refine your ideas. You can also type plain text under any outline level. If you move that outline level, the text will go with it.

You create an outline heading by pressing Alt-Enter. If the file is empty, that will create a level-1 heading, which is marked by one asterisk.

If you want to create a level-2 heading, then press Alt-Right Arrow. When you insert a heading, Org will automatically make it the same level as the previous heading. You can then demote the heading with Alt-Right Arrow, or promote it with Alt-Left Arrow.

To give you an example, in my mintcast.org file I use a Level-1 heading for each episode. Episode 8 was Linux User Groups, Episode 9 was Org-mode, etc.

Then I use a Level-2 heading for each section: Episode intro, News, Rothgar, Main Story, Web site of the week, and so on.

Then under News, I have a Level-3 headline for each news item. Then the text of what I want to say is written under that headline.

One of the nice things about an outline is that you can collapse the sections you're not working on, which keeps the display clean -- you don't get distracted by things you're not working on at the moment.

Although that can bite you. The first time I was using Org-mode to write the podcast, I had several headlines for news items and I would collapse the ones I wasn't working on. But then I would forget which ones I had finished, and I would have to expand the item and read the last paragraph to see if it sounded finished.

But then I realized that Org already had a solution for that. Any headline can be a To-Do item, indicated by the word TODO in capital letters at the beginning of the line after the asterisks.

To convert a standard heading to a TODO heading, just put the cursor anywhere on that line and press Ctrl-C Ctrl-T. The first time you do this, it will become a TODO. The second time, it will change to DONE. Then if you do it again, it will become a standard headline again.

You can also define your own workflow. Instead of TODO and DONE, you might have a sequence like TODO, SCHEDULED, IN PROCESS, COMPLETE and VERIFIED. That's up to you -- you have complete control.

So when I'm working on the podcast, I make each headline a TODO item. When I finish that item, I click in the headline and press Ctrl-C Ctrl-T to change it to DONE. Now I can tell at a glance which items are complete.

Org provides commands that will show you all of your outstanding to-dos, not only in your current file but in all the Org files that you specify.

Since Org is an outliner, it's easy to move things around. For example, you can move a headline up or down by holding the Alt key and pressing the up or down arrow. When you move the headline, any subheadlines and any text under it will move with it.

I mentioned that you need to learn the Org keystroke commands. Just to complicate things a little further, sometimes you need to learn Emacs commands as well.

For example, when I was talking to the writer who used Org to write her fiction, I asked if you could edit the same file in two windows. And Org -- well, Emacs -- actually calls those buffers. That's one of the new terms you need to learn. Files are what is stored on disk. What you see on screen, what you're editing, is a buffer. When you save it, it becomes a file.

Anyway, she assured me that yes, you can edit a buffer in two windows. This would allow me to keep my story notes in the same file with the story, and edit them both at the same time.

But when I got ready to do that, I could not find the Org command to split the window. It finally dawned on me that this was not an Org command, it was an Emacs command. Then it was easy to find. To split a window vertically, press Ctrl-X and then the number 2. To split a window horizontally, press Ctrl-X and then the number 3. To move to the other window, press Ctrl-X and then the letter O.

Installing Org is another topic where it's not as easy as other applications.

First, you need to install Emacs. If you're using Ubuntu or one of its derivatives like Linux Mint then it's in the repository, so that part is easy.

Then you need to install Org-mode. The repository for Mint and Ubuntu has Org, but it's an old version. To get the current version, you need to go to the Org web site.

There you'll find a link for the standard distribution. This gets you a file that you can extract and install, but only if you understand how to install modes in Emacs. If you don't understand that process -- and I don't -- these instructions will be meaningless to you.

If you look a little further down the page, you'll find a section called Alternative Distributions. That will take you to a page where you can download it as a DEB file. Once you get that file, just double-click it to install Org.

In this article I've talked quite a bit about Org, and I've barely scratched the surface. I've seen demos where they planned a project, scheduled their entire agenda, and generated some beautiful PDF reports from Org-mode.

If any of this sounds interesting, I suggest you go to the Org-mode web site and check out the tutorials. I think it's best to start with the screencasts, then read the web pages.

And remember that you don't have to be an expert on the whole thing to get started. I haven't learned much beyond basic document organizing, but I've been using Org quite effectively for that. Next I plan to learn more about agendas and project planning. I'll talk about that in a future article.

 

Charles Olsen is a writer, trainer and IT professional. He can be reached at charles.olsen@pobox.com. See more articles at and listen to the mintCast podcast at http://mintcast.org.