Note on Org-Mode for Emacs

2010/10/11

1 Overview

Org-Mode is an Emacs mode tailored for keeping notes, TODO lists and
general planning in an easy to use plain-text environmnet. I have
just started to use it and it certainly gets my vote as it fufills my
needs for work. These needs are:

  • I need to write up rough drafts quickly of notes from
    class/studying/research;
  • Have a planner to prioritise my time;
  • Incorporate existing workflows ;
  • Terminal based and/or can beintegrated with version control systems
    such as git or bazaar or svn; and
  • Be easy to use with an option to export to some better format for
    typesetting or viewing.

I use org-mode either to outline documents and fatten them out with
text and use TODO items to help organise that writing, or to manage my
life with todo items. For more information concerning org-mode see the references at the end of the post.

For this post I am simply going to introduce org-mode and its common
syntax and basic abilities. In a future post I shall go more into
depth how I use it for planning and GTD, moreover I might write a
tutorial on how I used it for outlining documents.

2 Setup

First some setup code. I have the following code placed in my .emacs
file:

(setq org-log-done t)
(setq org-export-with-toc 4)
(setq org-export-headline-levels 4)
(setq org-startup-folded "showall")
(setq org-startup-align-all-tables "align")
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
(add-to-list 'auto-mode-alist '("\\.todo$" . org-mode))
(add-to-list 'auto-mode-alist '("\\.note$" . org-mode))

The first line adds time stamps to completed TODO items. The second
and third lines limits the table of contents, on export, to a depth of
four and limits heading depths to four within a file. The fourth
ensures that code folding is disabled. The final setting ensures that
tables are aligned. The last three lines forces emacs to open all
*.org, *.todo, and *.note files in org-mode. This is just a handy way
for me to organise my files as I see fit.

3 Exporting

Org-mode files can be exported to several formats such as docbook,
html and LaTeX. To export and get a list of available formats enter:
C-c C-e. Direct exportation is as follows:

HTML C-c C-e h
LaTeX C-c C-e l
DocBook C-c C-e D

4 Planner Mode

The core use of org-mode is as an outliner/planner. Headings are
rather trivial:

 
* Level 1
** Level 2
*** Level 3

and so on. Headings can also be indented and single stars used with
org-indent-view, but I do not like that.

4.1 Todo -Items Basics

When used as a planner each header acts as a TODO item and each of its
children and childrens children, are counted as sub-tasks. After the
header level indicator a state tag can be added that indicates the
status of the TODO item. The standard states are: TODO and
DONE. To rotate between states enter C-c C-t.

4.2 Adding States

Additional custom states can be added at the start of the file as
follows:

#+TODO: TODO FEEDBACK | DONE CANCELED
#+TYP_TODO: FEEDBACK | DONE CANCELED
#+SEQ_TODO: FEEDBACK | DONE CANCELED

Where all the states to the left of the vertical bar indicate
unfinished states and to the right finished states. Also appending
(char) to each state i.e. FEEDBACK(f) can add a fast action key
combo accessed by C-c C-t char

Global workflows can be added in your .emacs file as follows:

(setq org-todo-keywords
      '((sequence "TODO" "|" "DONE") ;; Classic
        (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
        (sequence "ALICE" "BOB" "|" "DONE")
))
Note
either of the above lines can be used.

4.3 Using States

The states of TODO items can be used in whatever way you
wish. There can even be support for different workflows The org-mode
manual provides two examples.

4.3.1 Types i.e. Task allocation

The states can be used to indicate who is to be allocated the
task. For example:

 
#+TYP_TODO: ALCE BOB CHARLIE MALLORY TIM | DONE

can be used to assign tasks to the people mentioned.

4.3.2 Bug Reports

Bug reports have different states which can be represented as:

 
#+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED

4.4 Progress

After task declaration use [ % ] or [n/m] to indicate completion.
The value will be updated with the children

* Organize Party [33%]
** TODO Call people [1/2]
*** TODO Peter
*** DONE Sarah
** TODO Buy food
** DONE Talk to neighbor

4.5 Checkboxes

Plain lists can be turned into todo items by adding [] at start i.e.

* TODO Organise Party [/]
  - [-] Call People
   - [ ] Alice
   - [X] Bob
  - [ ] order food

4.6 Tags

Labels and Tags are used for context. Form is :tag: Add tags with
C-c C-q or after colon M-<tab>

Type Command
File Tag #+FILETAGS: :tag:tag1:
Labels #+TAGS: @tag1 tag1
Tag Sets #+TAGS: { @work @home }

The tag sets are mutually exclusive. The @ character is not
important. Appending (char) to end of tag definition to add short
cut i.e.: @work(w).

4.7 Timestamps

Type Command Result
Active C-c . < 2006-11-01 Wed 19:15 >
Inactive C-c ! [ 2006-11-01 Wed 19:15 ]
Repeated nvt < 2006-11-01 Wed 19:15 +1w>
Range nvt <timestamp>--<timestamp>

4.7.1 Deadlines and Schedules

Deadlines and schedules can be appended to headlines as follows:

Deadlines C-c C-d
Scheduled C-c C-s
Note
scheduled implies when it starts.

5 Note Taking

Before, I used to write-up notes either directly in LaTeX or Markdown
(or varient of) as an intermediate form before conversion to LaTeX for
refinement. I have been also tempted to use reStructuredText or
Sphinx, and also play with pandoc as a converter between
formats. Although the aforementioned tools did give me a nice work
flow for note taking, the planner aspect did not work. For my todo
lists, I used to have simple markdown file full of lists combined with
a iCal calendar to mark it up in a calendar. Org-mode combines the two
just nicely.

5.1 Taking Notes

Taking notes in org-mode is simple. The mark-up syntax is similar
and easy to learn like most markdown-esque languages. I shall only
list some of the core markup features that I use commonly. Headers are
same as seen when outlining/planning.

When using org-mode to take notes, I use to write out the bulk of the
text from the notes with placeholders, in the form of descriptive
lists to represent any figures, lemmas, et cetera. I then export the
notes to LaTeX and fill out the rest of the more latexy stuff
i.e. maths et all, in pure LaTeX. I am aware that one can enter LaTeX
in org-mode but I have yet to explore it.

5.2 Syntax

5.2.1 Metadata

 
#+TITLE: A Note on Org-Mode for emacs
#+AUTHOR: Jan de Muijnck-Hughes
#+DATE: [2010-10-11 Mon]
#+EMAIL: foobar@nowhere.com
#+DESCRIPTION: Overview on how to use org-mode for working.
#+KEYWORDS: ORG-MODE NOTES TUTORIAL

The above is the metadata that I include for most notes.

5.2.2 Markup

Markup Command Result/Note
Unordered List - + * avoid use of *
Ordered List 1. 1) nvt
Description List term :: description nvt
bold *bold* bold
italic /italic/ italic
code =code= code
verbatim use tildas
Horizontal Rule ----- i.e.\ 5+ dashes nvt

5.2.3 Footnotes

Type Command
Regular Declaration [fn:<label>]
Regular Definition [fn:<label>] <text>
Inline [fn:<name>:<definition>]
Anonymous [fn::<definition>]

5.2.4 Hyperlinks

Type Command
Standard [[link][description ]
Raw Link [ [link ]]
Document Target <<Target>>

5.2.5 Tables

| Header  | Header 1 | Header 2 |
|---------+----------+----------|
| Content | Content  | Content  |

5.3 Blocks

There are several types of blocks that you can define, the manual has
more, but the ones that I use most often are: Quotes, Examples and
Source code.

5.3.1 Quotes

 
#+BEGIN_QUOTE
People sometimes ask me if it is a sin in the Church of Emacs to use vi. 
Using a free version of vi is not a sin; it is a penance. So happy hacking.
   --- Richard Stallman
#+END_QUOTE

5.3.2 Examples

 
#+BEGIN_EXAMPLE
#+BEGIN_QUOTE
...
#+END_QUOTE
#+END_EXAMPLE

Alternativly, the format : that is a space colon space also works
and it’s much quicker.

5.3.3 Source Code

 
#+BEGIN_SRC <emacs mode>
...
#+END_SRC

This is a cool feature of org-mode. You can add code in a block, label
it with its mode and it will be highlighted as appropriate in the
buffer. A list of languages can be found here. Furthermore, if you
execute the commad: =C-c ‘= this will launch a separate buffer to
enter the code in.

6 Further Reading furtherReading

A lot of org-mode functionality has been left out. More information
can be found online. Some quick lines:

Author: Jan de Muijnck-Hughes

Date: [2010-10-11 Mon]

HTML generated by org-mode 6.36c in emacs 23