Aja Hammerly

Aja Hammerly

Five Useful Org-Mode Features

As I am writing tutorials, working on new code, or creating my talks I usually take notes. A couple of years ago I adopted org-mode in Emacs for my notes. I mostly use it as an outlining tool. Each step of a tutorial or each section of a talk gets a headline, and I can collapse and expand sections to help me focus. When I’m writing code, I’ll use the outline mode to track user stories and create sub-bullets to break it down as needed. I often put code snippets or questions as detail in my outline so I can recreate what I did later as needed.

Org is good for much more than outlines. If Emacs is an operating system, Org is the task tracker, time tracking, spreadsheet, flashcard app, and note taking application for that operating system. Here are a couple of my favorite Org features.

Tables and Spreadsheets

Tables

Org has a built-in table editor. To create a table just type an ASCII art table like this:

 | Cat Name  | Owner Name |
 |-----------+------------|
 | Emma      | Aja        |
 | Nick      | Aja        |
 | Mr Squeak | Elyse      |

Org takes care of aligning the columns for you. You can also build tables by typing C-c | and Org will prompt you for the dimensions of the table and include a header row automatically. Moreover, if you have existing data in CSV form, you can highlight the data and type C-c | to get your CSV converted to a table as well.

There are also commands to move, add, and delete rows and columns. For more info check out the resources below.

Spreadsheets

Earlier this week I had some analytics data in an Org table and quickly needed sums for a few columns. I thought about trying to move it to a spreadsheet app but decided to see if Org could do the calculations. It turns out it can.

Since it is Girl Scout cookie season here in Seattle here is a table tracking the sales of several fictional Girl Scouts.

| Scout  | Mints | Peanut Butter | Shortbread |
|--------+-------+---------------+------------+
| Ann    |    23 |            12 |         34 |
| Betsy  |    74 |            35 |         52 |
| Carmen |    10 |             8 |          3 |
| Daphne |    42 |            46 |         12 |

I want to have a total column for each scout and a column for each type of cookie. I add the necessary columns and rows to get this:

| Scout  | Mints | Peanut Butter | Shortbread | Total |
|--------+-------+---------------+------------+-------|
| Ann    |    23 |            12 |         34 |       |
| Betsy  |    74 |            35 |         52 |       |
| Carmen |    10 |             8 |          3 |       |
| Daphne |    42 |            46 |         12 |       |
|--------+-------+---------------+------------+-------|
| Total  |       |               |            |       |

Like most spreadsheet applications Org has shortcuts for referring to cells, rows, and columns. Columns are one indexed and prefixed with dollar signs: $1 for the first column for example. Rows are referred to with @ and 1 indexed as well (including any headers!). @2 is the second row, and @-1 is a shortcut for the last row. Ranges are specified with .. so $2..$4 is the second through the fourth column in the current row. If you forget the syntax type C-c } in a table cell and Org will annotate the table with reminders.

To add a formula summing all of Ann’s sales, type =vsum($2..$4) in the total column at the end of Ann's row. Type C-c C-c and emacs will calculate the value. To fill in the rest of the column type C-u C-c *. To sum the columns you use =vsum(@2..@-1)` in the bottom row. Here’s what the resulting table looks like.

| Scout  | Mints | Peanut Butter | Shortbread | Total |
|--------+-------+---------------+------------+-------|
| Ann    |    23 |            12 |         34 |    69 |
| Betsy  |    74 |            35 |         52 |   161 |
| Carmen |    10 |             8 |          3 |    21 |
| Daphne |    42 |            46 |         12 |   100 |
|--------+-------+---------------+------------+-------|
| Total  |   149 |           101 |        101 |       |

Todos and Checklists

Many people use Org as their task manager and time tracker. I’m not there yet (still an Omnifocus and paper planner person) but I do use the task tracking when working on user stories or testing tutorials I have written using Org. Here’s an example from the Org file I used to outline this post.

** TODO Todos and Checklists [50%]
*** DONE Todos
- Todo Cycling C-c t
- Customizing your todo cycle
- Summarizing todo status?  [5%] or [/] after a todo item
*** TODO Checklists [0/2]
- [ ] Basic checklists
- [ ] Nested checklists
  - [ ] Item One
  - [ ] Item Two
Check of items with C-c C-c

Todos

To create a todo item just put TODO in all caps at the start of an outline heading. You can also toggle the todo state of a heading by typing C-c t. Once you complete the task, you can type C-c t again to toggle the status to Done. The list of states Org cycles through can be customized by setting the org-todo-keywords variable. That variable also allows you to set multiple workflows as long as they use unique keywords. To show an automatic status summary put [%] or [/] after a todo heading. Org will automatically calculate the status summary of any child headings.

Checkboxes

Org also supports checkboxes. Plain lists in Org have a single dash, -, in front of each item. To convert a plain list to a checklist put [ ] before each item. The space between the square brackets is necessary. You can nest lists of check boxes and use [%] and [/] for summaries just like with todos. To check off an item, you can type an X in the box or use C-c C-c.

Tags

If you find yourself struggling to find things in your Org files, you can use tags. A tag is just a word preceded and followed by a colon, :blog_post:. Every heading can have multiple tags.

You can type the tags with the colons or use C-c C-c and specify the tags in the minibuffer. Org will autocomplete using the tags already in your buffer. If you want to specify a list of tags to use in a given file you can do that with Org metadata like this:

     #+TAGS: blog_post video twitter code

To search a buffer for tags us C-c \. Org mode will hide all the content that doesn’t match your search.

Org and Code

When I’m working on a tutorial I plan to publish, I use Org’s syntax for embedding code blocks.

    #+NAME: <name>
     #+BEGIN_SRC <language> <switches> <header arguments>
       <body>
     #+END_SRC

Here’s an example from the notes doc for my RailsConf 2016 talk:

    #+NAME: vision_example.rb 
     #+BEGIN_SRC ruby
       require "gcloud/vision"
       
       v = Gcloud.vision
       i = v.image "gs://railsconf-postcards/fremont-troll.jpg"
       a = v.annotate i, landmarks: 10
     #+END_SRC

Typing C-c ' while in the code block brings up an editor using the correct major-mode (assuming your have it installed). Saving in the editor saves in your Org document.

There are many more things you can do with code in Org. You can extract the code to a separate file or use Babel and Tangle to evaluate code inside org.

It is Just Text

The real place Org shines though is in just being text. If I share an Org file with a co-worker, who doesn’t use Emacs or doesn’t even use a text editor they can still read it and use the contents. Some of the features, like progress summaries for checkboxes, won’t work but the meat of the document is entirely usable. If I had used a word processor or task management app that wouldn’t be true.

Moreover, I’m happy to say that GitHub pages render Org like they do for Markdown. To see it for yourself check out the Org file I used while writing this post, example.org.

Learn More

If you want to learn more here are some of the resources I used while writing this post.