Several months ago, I got so sick of TaskPaper asking me for my password so it could sync that I stopped using it entirely and went back to keeping my to-do lists in Markdown files synced via Dropbox. On Halloween, a new version of TaskPaper came out that—finally!—drops the homemade syncing system and uses Dropbox instead. I quickly converted my lists to TaskPaper format and am happily using it again.

## Background

TaskPaper is a list manager program available in both Macintosh and iPhone/iPad flavors. It keeps its lists saved in plain text files using a format that similar to, but not quite, Markdown. But it displays the lists in rich text and has methods for moving and hiding list items that are similar to programs like OmniOutliner and OmniFocus.

Here’s what an example list looks like on the Mac

and on the iPhone

The file itself looks like this:1

Administration:
- send company information to McIlroy
- clean out old files
- follow up on 60-day unpaid invoices
Thompson Project:
- get design history
- calibrate test equipment
- get fixture hardware
- set up text fixture (2 days)
- run tests
- report
Ritchie Project:
- hand analysis for scale (1 day)
- build finite element model (4 days)
- analyze
- report (due 4/15)
Kernighan Project:
- waiting for equipment manuals and test protocol (followup call on 3/20)
- review client photos


In TaskPaper’s nomenclature, projects are the things that end with colons and are displayed in bold, tasks are the things that start with a tab and hyphen and are displayed in normal weight. (There are also notes, which I seldom use. These don’t use leading hyphens or trailing colons and are displayed in gray text.)

I think you can see from this example what attracted me to TaskPaper: it looks good with clean, simple formatting but is easily hackable because of its plain text basis. One of the first things I did when I started using TaskPaper was whip up a script for printing my lists on 5×7 index cards for inserting into my planner notebook and on 3×5 cards for sticking in my pocket for quick reference (the latter is mainly for shopping lists). TaskPaper has always struck me as a best-of-both-worlds sort of app.

## Syncing, past and present

“Best,” however, would not be the word anyone would use to describe TaskPaper’s syncing system. It was a kludgey thing, written before Dropbox made its APIs public. It required a separate program running in the background on your Mac, and, most maddeningly, kept asking for your Google password at the most inopportune times. It drove me crazy.

Jesse Grosjean, TaskPaper’s developer, knew that his syncing system was an annoyance and announced that he would move to Dropbox syncing in all his apps. That was in June of 2010. After the announcement, he brought out PlainText with Dropbox syncing, then switched WriteRoom to Dropbox syncing. But TaskPaper lagged. Eventually, I couldn’t stand the inconvenience anymore and stopped using it sometime early this year. I figured Jesse had abandoned Dropbox syncing for TaskPaper and it was time to move on.

I tried other list managers, but never liked any of them. I stuck with Markdown-formatted lists because they worked, but they weren’t fun to use or easy to rearrange. So I was happy to see the magic words “Added Dropbox.com sync” in the release notes for TaskPaper 2.0 for iOS. I immediately reinstalled it on my phone and have been using it ever since.

One thing I’ve had to get myself used to again is the distinct difference between the Mac and iOS versions when it comes to entering information. Typing entries into the Mac version is very much like using any text editing application—the main difference being that leading hyphens and trailing colons cause the entries to change their formatting. Editing an existing entry works as you’d expect: click where you want the insertion point to go and start typing. Marking a task as completed is done by clicking on its handle, which causes it to be struck through with a horizontal line. Reordering items is done by dragging the handles to their new locations.

The iOS app, on the other hand, is much more modal. The entire entry is a handle, so tapping on it doesn’t allow you to start editing, it selects the item so you can drag it to a new position. I assume Jesse made it this way because he felt that handles on the ends of lines would be too small to be good targets. To mark a task as done you swipe through it from left to right, which—as in the Mac version—causes it to be struck through with a horizontal line. To edit an item you need to double-tap on it.

Unfortunately, when you’re done editing one one item, you can’t just tap on another to edit it; even though the keyboard is onscreen, you have to double-tap on the other item to move the insertion point into it. In effect, the double-tap exits edit mode in one entry and restarts it in another. This seems wrong at first because it looks as if the entire document is one big text field, and your instinct is that you ought to be able to move the insertion point anywhere within the document with a single tap. The behavior only makes sense when you get used to the idea that each list entry is its own text field, separate from all the rest.

The iOS app has one trick that’s so important for efficient list making that Jesse’s put it in the “Tips and Tricks” document, in the Help, and as the first entry in the online FAQ: it’s how to change the type of an entry on the fly.

When you’re entering tasks one after another, whenever you tap the Return key TaskPaper helpfully inserts the task-starting hyphen for the next entry.

What if you don’t want the next entry to be a new task? There’s a way to change an entry from one type to another through a menu, but that requires you to leave editing mode first. The fast way to change a new entry’s type is to tap Return again before you type any characters. That changes the entry from a task to a note.

Tapping the Return key a third time changes the entry from a note to a project.

If you made a mistake and went past the entry type you wanted, you can keep tapping Return to cycle through the three entry types again and again.

## Converting to and from Markdown

When I decided to switch back to TaskPaper, I had a few lists in Markdown format that I needed to convert. They looked like this:

# Administration #
- send company information to McIlroy
- clean out old files
- follow up on 60-day unpaid invoices

# Thompson Project #
- get design history
- calibrate test equipment
- get fixture hardware
- set up text fixture (2 days)
- run tests
- report

# Ritchie Project #
- hand analysis for scale (1 day)
- build finite element model (4 days)
- analyze
- report (due 4/15)

# Kernighan Project #
- waiting for equipment manuals and test protocol (followup call on 3/20)
- review client photos


I didn’t have very many lists and could’ve easily done the conversion by hand, but if you read this blog regularly, you know how hard I find it to resist the siren call of scripting. So I whipped up a short shell script to convert from Markdown to TaskPaper format.

#!/bin/bash
sed -E -e '/^$/ d ' -e 's/^-/ -/' -e 's/^# $.+$ #$/\1:/' $1 | unexpand -t4  It consists of three sed parts: • Deleting the blank lines between projects. • Putting four spaces at the beginning of each task. • Replacing each hash-delimited header line with the header text followed by a colon. The -E option to sed tells it to use extended regular expression syntax, so I get to use unescaped parentheses for grouping and + as the “one or more” metacharacter. The last step in the pipeline replaces the leading four spaces of each task with a tab through the unexpand command. While I was at it, I figured I might as well write one that does the opposite conversion: #!/bin/bash expand -t4$1 | sed -E -e '/:$/ i\ \ ' -e 's/^(.+):$/# \1 #/' -e 's/^    //' | sed '1 d'


This pipeline starts by expanding tabs to four spaces, then it does a three-part sed command:

• Inserting a blank line before every line that ends with a colon. (This makes the first line of the file blank.)
• Changing the colon-ended lines to hash-delimited lines.
• Deleting the four spaces at the beginning of each task line.

The last step of the pipeline is another sed command that deletes the first (blank) line. At first, I thought this step could be just another -e part of the previous sed command, but that didn’t work. Apparently, sed doesn’t “know” about the inserted blank line at the beginning of the file while it’s still running.

I should mention that these scripts are very simple-minded and don’t cover nested projects and lists, which TaskPaper can generate. That didn’t matter to me because I don’t use nesting in my lists. If I did, I probably would have gone with full-blown Python scripts instead of a simple shell pipelines.

Update 11/14/11
I had no idea Brett Terpstra had already written a TaskPaper-to-Markdown conversion script (which Lri has done a variation on), but I should have guessed. It’s more complete than mine, of course, but I take comfort from the fact that he hasn’t written a Markdown-to-TaskPaper converter. Yet.

## Finally

TaskPaper isn’t especially cheap by today’s cutrate standards. The Mac version costs $30 and the iOS version costs$10. I probably wouldn’t have gotten started with it on the Mac if it hadn’t come with a MacHeist bundle a few years ago. And I would’ve missed out on an app that almost perfectly fits my list-making, task-handling needs. In addition to the usual to-do lists, I use it to make packing lists for business trips and vacations and for grocery and other shopping lists. It doesn’t have the giant feature set of OmniFocus, but for me simpler is better.

1. Almost. TaskPaper uses a tab character at the beginning of each list item. For layout purposes here on the blog, I’ve replaced each tab with four spaces.