Using org-mode

Introduction

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)
                                   Info-default-directory-list))))
    ;; 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");
  }
#+end_src
*** 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:

#+begin_example
  This is a line from an error log
  This is another line from an error log
#+end_example

You can either type

#+begin_example

#+end_example

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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s