The TaskPaper RD Notebook

2014-02-03

Page content

This is part two in the series. In part one, I discussed the rules and detail designs of a plain text based task management experiment. The tag and project structure in the TaskPaper format is flexible and easy to comprehend. But the system is only as good as the tools available for working with the documents.

In this article, I’ll document a broad set of tools available on various platforms for working with TaskPaper documents. This will not be a description of the “ideal” but rather a catalog of options. Some work very well and some are unsatisfying.

I’ll also mix-in some of my own custom tools and conclude with a small initiative to help expand on the available tools.

If you are looking for a solution, this is not it. If you are looking for my R&D notes, then you’re at the right address.

The Tools

One of the great things about plain text systems like TaskPaper is that pretty much any application that can read and write txt files can do the basics. The downside is that most tools just do the basics.

I’m attempting to string together many disparate applications and scripts to accomplish what OmniFocus does with a single platform.¹ Some solutions work almost perfectly without any tweaking but on iOS, it’s a Sisyphean feat to have full control over a task list.

I’ll lay out what I’ve found and how I’m attempting to use it below.

Alarming Events

Let’s clear this up right away. TaskPaper and similar apps are not active tools. They don’t grab you any more than a paper notebook would. While OmniFocus incorporates alerts at a basic level, it’s never been my preferred tool for reminders. I’ve always found OmniFocus to be too passive and easily dismissed (or missed) to rely on the notifications.

I’ve used Due.app on Mac and iOS for quite awhile. There’s a lot to like about Due. It has terrific plain-english syntax and flexible repeat reminders. Because the apps all sync through Dropbox or iCloud, I’m much more likely to get the message.

Due.app also has a great URL scheme which means that it can integrate well with Drafts or Editorial.

There are also a few downsides to Due.app. The syncing requires me to open the app on iOS periodically. It’s not a terrible burden, but also not ideal.

Second, Due is outside of my other scheduling apps, like calendars and Outlook. It’s nice having a place to see everything in the coming week all at once.

It’s also not easy to segregate and categorize all of the reminders in the Due app. Some are for work and some are for personal tasks. But in Due, it’s just one long list of everything.

Apple’s Reminders.app is a viable alternative to Due.² It integrates with various calendar apps, including Outlook by way of Exchange. With apps like Fantastical, I can use plain English to enter an alert. Reminders syncs across iOS, Mac and Exchange and includes a web app option when all else fails.

The Reminders app provides enough customization for repeating tasks and includes options for location based reminders, which I rarely use.

The big benefit to Reminders is that I can categorize groups of reminders and share them with my wife. While I appreciate the complex repeating options available in Due.app, I’ll probably stick with Reminders.app for all of the other reasons, not to mention that it’s pretty hard to miss an alert from Reminders.

TaskPaper for Mac

This falls into the “Almost Perfect” category. Being the origin of the format, the Mac application TaskPaper supports all of the syntax I need. Through AppleScript, anything that’s not immediately available can be added.

TaskPaper obviously shares it’s streamlined interface with the closely related Mac app, WriteRoom, from the same developer. The interface is sparse, which is a nice change from many of the toolbar laden apps I’ve worked with. While the basic themes in TaskPaper are pleasant, they feel a little dated. I’ve switched to the excellent HelvetiCan Theme.

TaskPaper Query Language

The single most powerful feature of TaskPaper is the smart search which replicates and exceeds “Perspectives” in OmniFocus. Using the logical and powerful query syntax, it’s possible to slice and dice a large task list at will.

The syntax is a combination of natural language and attribute flags. The TaskPaper documentation describes it as an attribute search term relationship:

:::text
<attribute> <relation> <search term>

For example, to limit the view to a single project, use the obvious project Trash Compactor Malfunction or use a the attribute syntax project=Trash Compactor Malfunction. You can also use the relation operator “contains” for more general queries like project contains Trash to find all projects that contain the word “Trash”.

Working with tags is equally flexible. Any tag, including completely arbitrary tags, can be search. For example, given some tags like @parsecs(1) @parsecs(2) you can construct an apparently logical query like @parsecs < 2 to find all tasks and projects with an @parsecs tags with attributes less than 2.

An extremely valuable option is to negate a specific tag. For example I generally append not @done to a most queries so that I do not see the tasks or projects that are complete.

Date attributes are also valuable search options in TaskPaper and respond to boolean syntax such as @start < 2014-02-02.

Through combinations of search terms and attribute relations, there’s a huge variety of options in TaskPaper to evaluate a project or a day’s activities. Here’s some that I’ve found particularly useful:

In Progress Tasks:

:::text
not @done and not @cancel and not @hold and (@started or @draft or @waiting or @today)

Stalled Tasks:

:::text
not @done and not @cancel and (@hold or @waiting)

Available Tasks:

:::text
not @done and not @cancel and not @hold and (@start <=  2014-02-02 or @due <=  2014-02-02 or @today)

All Tasks and Projects with a due date (+d shows descendants as well):

:::text
@due+d

Saved Searches in TaskPaper for Mac

The most significant drawback to TaskPaper for Mac is that it lacks the ability to save and organize these smart searches. Luckily, there are a few solutions.

First, are TextExpander shortcuts. Expand a shortcut to instantly narrow the task list. There’s more power here that an initial glance might suggest. TextExpander has excellent support for time-stamp math which opens an entirely new level of sophistication in TaskPaper queries.

I’ve mapped the “Available Tasks” query about to the following TextExpander shortcut:

:::text
not @done and not @cancel and not @hold and (@start <=  %Y-%m-%d or @due <=  %Y-%m-%d or @today)

This is simple enough. The date placeholders are expanded to today’s current date.

Here’s a variant to show all items available soon:

:::text
not @done and not @cancel and not @hold and (@start <= %@+5D%Y-%m-%d or @due <=  %@+5D%Y-%m-%d or @today)

This uses the TextExpander date math to expand the date for 5 days in the future and limits the TaskPaper list to all items with an @due or @start date less than or equal to that date.

Diversion: TextExpander

One of the easiest ways to get around the lack of saved searches in TaskPaper is through the use of TextExpander snippets. This is a basic filter for late tasks. It uses the TextExpander date functions to look for anything tagged with a @due date of today or earlier.

:::text
not @done and not @cancel and not @hold and @due <=  %Y-%m-%d

This snippet is useful for checking on Available Tasks:

:::text
not @done and not @cancel and not @hold and (@start <=  %Y-%m-%d or @due <=  %Y-%m-%d or @today)

Here’s a TextExpander snippet for tasks and projects that will be available in the next 5 days. It uses the Date Math function to automatically enter the date 5 days in the future:

:::text
not @done and not @cancel and not @hold and (@start <= %@+5D%Y-%m-%d or @due <=  %@+5D%Y-%m-%d or @today)

Any of these snippets can be applied on the fly and combined with other search terms. So, if you want to look at overdue tasks on a specific project, just enter project contains Trash followed by the snippet shortcut.

More Options for Controlling TaskPaper

I’ve employed Keyboard Maestro as a helper application for some my more obscure saved searches.³ Rather than write TextExpander snippets and create separate macros, I use KM to enter the TE snippets. The macro group is pretty simple in functionality. It activates TaskPaper and expands the snippet in the search field.

TaskPaper is a highly scriptable application. I’ve discovered that almost anything I want to accomplish is accessible through AppleScript. Just browse through the TaskPaper AppleScript Wiki to get an idea of the wide variety of tools being developed to work with the application.

There’s a script to move tasks from a Reminders list into TaskPaper. Or how about moving tasks from TaskPaper to the Reminders app? If you’re a BusyCal user, then grab the TaskPaper to BusyCal bundle.

There’s a Script to convert TaskPaper entry types. Or if you want to go full-nerd then check out the Taskpaperparser project which converts a TaskPaper document into an AppleScript “object” for manipulating the entire project/task model.

I’ve see many scripts and workflows for handling automatic date conversion and updating of due tags.

The TaskPaper format is so flexible and easily parsed that entire time tracking systems have been built off of it. I think you get the idea. The sky’s the limit when you’re working with plain text.

This is an area that benefits from the flexibility of the TaskPaper format. Since tags and attributes are completely free-form in TaskPaper, I’ve been able to create ad-hoc grouping of tasks and projects:

:::text
Death Star: @review(weekly)
Hoth Probe: @review(weekly)
The Ewok Infestation: @review(weekly)

TaskPaper also provides quick entry of new items through system input panel available with the hotkey combination ⇧+⌘+⏎. This integration goes a long way at replacing the OmniFocus inbox on the Mac.

But of course, there are alternatives through helper applications like Alfred. Here’s an Alfred Workflow for adding and accessing tasks. Pedro Lobo also brings us a clever extension of the TaskPaper notes functionality but accessible through Alfred.

Clearly the Alfred entry point for TaskPaper is a popular one. This TaskPaper for Alfred package goes one step further and creates a “bump” action to move a task’s due date to tomorrow. It also provides some GeekTool functionality.

Rob Trew began providing scripts for converting plain text lists to OmniFocus back in 2012. I have a suspicion that we’ll start see tools from him that move items the other direction in 2014.⁴

Brett Terpstra has been working with TaskPaper for several years and has developed little utilities like his TaskPaper logger for Day One and his Next Actions CLI for working with TaskPaper from the command line.

Folding Text

There’s also TaskPaper’s cousin, FoldingText for Mac. While FoldingText supports the tags in TaskPaper, it is really designed for working with Markdown. There is no easy way to focus on a project or tag in Folding Text.

However, it’s clear that Folding Text is the future for TaskPaper. The development version of Folding Text has received significant updates and is built on a much more flexible text filtering model. There’s even a new SDK available. My money is on Folding Text replacing TaskPaper in the coming months. I also believe this will be a major step forward in plain text task management, given Folding Text’s central focus is on text editing with time management features added on top.

Sublime Text

Sublime Text with the PlainTasks package is a serviceable task manager with TaskPaper formatted text files. It’s not as efficient as the TaskPaper Mac application but there are some basic features that make it a very useful tool. It’s worth noting that the package receives regular updates and it works on Mac, Windows and Unix.

The PlainTasks package is popular and I’ve seen several useful forks and additions. Jonathon Poritsky put together a nice alternative styling to PlainTasks that’s worth installing.

Because Sublime Text has powerful search features, it’s fairly easy to keep on top of tasks. Just hit Shift+ctrl+F and search for a tag to get a clickable perspective-like view.

But there are major shortcomings too. There’s no direct way to filter by start or due dates or to focus on a single project. You can perform the following regular expression search to narrow the view a bit:

:::regex
@due\(2014\-[01|02]\-\d\d\)

This finds “@due” tags with dates of January or February of this year. This could be done with smart TextExpander snippets but it’s just slightly awkward on Windows.

One nice feature of Sublime Text’s PlainTasks is the project folding implementation. It’s nice to quickly expand and collapse sections of a larger file.

There are several shortcuts in the PlainTasks bundle that make working with TaskPaper files convenient. Hitting ^+d appends the @done tag with the current date stamp. Hitting alt+c will append the @cancel tag.

Type s,tab,tab to mark an item as @started or t,tab,tab to mark a task for @today

The PlainTasks package also provides a clean-up function. Hit the shortcut ⌘+⇧+a to archive @done tasks to the bottom of the current file and adds an @project tag that indicates the original source project that it came from.

Sublime Text provides a couple of generic functions that work well with the PlainTasks package. Hitting ^+r displays a list of all projects and selecting one from the list instantly jumps to that point.

The ^+⇧+f search option in Sublime Text is convenient for creating Perspective-like views of tasks. Search on @today to get a list of just the tasks for today.

I’ve added the folder with my task files as a project in Sublime Text, so I get the added benefit that the “Search in Files” command automatically highlights results in all of my TaskPaper documents.

You can also use the standard Sublime Text tools to manipulate tasks. The ^+⇧+up or down functions can move a line (task or project) up or down in the file.

Perhaps with some additional plugins, Sublime Text will become a full-fledged tool for TaskPaper formatted files, but it is a bit rough right now. To that end, I’ve been developing some of my own Sublime Text functions that make it a bit easier to quickly show available tasks and projects in the current TaskPaper file.

MailMate

Just last week Pedro Lobo unveiled a MailMate plugin based on AppleScript examples from Ryan Lane. This plugin sends the currently selected message in MailMate to either the front-most TaskPaper document or a predefined document. As a huge fan of MailMate, I like the direction this is going and shows some of the promise of this format for building custom tools.

GeekTool

GeekTool is a popular utility for displaying content on the desktop. Of course there is significant overlap between the kind of person that uses TaskPaper and the kind that uses GeekTool. The TaskPaper Parser project puts some of your tasks on your desktop.

The older set of scripts that are part of the GeekTool TaskPaper XML parser laid a great foundation that seems easy to work off of for a variety of purposes.

iOS

TaskPaper

For iOS, TaskPaper is still the ideal solution. This is a problem, given that development and support has been discontinued. The best features in TaskPaper are the smart search-and-filter options as well as quick tag and project filtering.

But there are still major holes in the applications. Similar to TaskPaper for Mac, there’s no option to save a smart search for repeated use. One solution is to leverage the TaskPaper URL scheme from apps like LaunchCenter Pro. But remember in part one when I suggested using separate files for each area of obligation? That’s a problem for TaskPaper search since it’s not a global function.

This could be solved with judicious use of TextExpander, if only TaskPaper supported the new TextExpander API. Here’s a workaround that uses LaunchCenter Pro to open TaskPaper and place the TextExpander snippet for a query on the clipboard but this is really a short lived solution.

But, unless you already purchased TaskPaper for iOS, you can no longer get it. It’s gone from the App Store.

My conclusion is that TaskPaper for iOS was once a great start. But it’s lost its luster and has now been abandoned by the developer. Unfortunately, there is nothing that fully replaces it yet. There are some early opportunities but a long road ahead my deter customers looking for a replacement.

Listacular for iPhone

Listacular is the heir apparent to TaskPaper on iOS and is recommended by the TaskPaper developer. As of this writing, it is not a replacement. It lacks all of the query features and smart syntax of TaskPaper. It is currently just a smart list manager, albeit a very nice one. It includes features for easily rearranging items and added due dates but there is little else for working with a complex task list.

The Listacular developer is working on bringing the app up to the TaskPaper feature list but it’s hard to recommend it for anything more than quickly viewing and adding tasks at this point.

Editorial for iPad

Editorial for iPad does not natively support TaskPaper, but can be twisted into a fairly competent tool. If you insist on using the TaskPaper file extension, you can configure Editorial to recognize the files. I use the .txt file extension, like a reasonable person.

I’ve built several Editorial workflows to specifically process the TaskPaper format. This macro scans all files in the folder for the currently open file and displays tasks or projects with @due, @start dates of today or earlier. It also includes items with the @today tag. It excludes items that contain the @done tag.

I’ve created a workflow for quickly inserting tags by compiling a list of all tags in all files and displaying an alphabetical list. Choose one to insert at the current cursor position.

Or focus on a particular tag by choosing it from a list of all tags and showing tasks that contain a match.

Finally, here’s a similar workflow that shows a list of all projects in all files. Select one from the list to get a summary search result set that matches the project name.

Derrick Fay also has several workflows to replicate the TaskPaper workflow in Editorial.

On iOS, Editorial is proving to be the best solution for me. That might be a result of my level of comfort with creating new workflows but I’m very impressed with what can be accomplished with this file format in a very short time.

I’m looking forward to a day when the TaskPaper query syntax can be enabled by an Editorial workflow. That might be my ideal working environment.

Drafts

It’s no surprise that Drafts for iOS makes an excellent quick capture tool for plain text task lists. I’ve configured several actions for prepending tasks to my existing project files.

This creates a new entry at the top of the text file that looks like this:

:::text
- Get the Tie Fighter services @added(2014-01-27)

Palpatine's Birthday Party: @start(2014-01-25) @due(2014-02-13)
	Dinner party reservation:
        - Lookup Regal Beagal's phone number
        - Tally guest count
        - Book party @due(2014-02-05)
        - Confirm dinner party @due(2014-02-10)

In a small way, my disappointment in OmniFocus 2 for iPhone prepared me for this workflow. Since I ultimately only used it for quick capture, I don’t feel a strong desire to find a fully functional task manager for my iPhone.

Text Editors for iPhone

Because my TaskPaper documents are text files, I have the advantage of using any of my preferred text editors on my iPhone to search and edit my tasks. My primary requirements are that they provide a search option and arbitrary Dropbox navigation. I need the ability to move between my normal notes and task list and I don’t want to use multiple text editors.

Notesy: Quick access with global search.

Nebulous Notes: Nice editor with macros and customizable keyboard.

Write for iPhone: An attractive editor with a Markdown-centric keyboard

WriteRoom for iPhone was one of the best, but it’s been retired along with TaskPaper.

Byword has too many Dropbox sync errors to be useful.

Outliner Apps

Since these files are just plain text, I thought that a general purpose outliner app might be a useful way browse and edit. I was wrong. CloudOutliner can not import and export in plain text. CarbonFin Outliner mangles the indentation when exporting and adds dashes in front of projects. OmniOutliner for iPad does not provide an easy way to convert a plain text list to an outline. It was worth a shot.

I also tried Workflowy but the formats were not perfectly compatible.

Pythonista

Here’s another gem from Pedro Lobo and Phillip Gruneich. It’s a Pythonista script for propagating the @done tags to all sub-tasks in a completed project.

There are additional options listed under the Miscellaneous sections that also apply to Pythonista.

Additional Options

Phillip Gruneich has been developing some interesting alternatives for use on the iPhone that rely Launch Center Pro.

Miscellaneous Tools and Scripts

I’ve discovered that there are many different reasons why people use the TaskPaper format, but there are an equal number of ways that they use it too. There’s some truly impressive work out there. Most of it requires an intense desire for a particular solution and the technical knowledge to make it work. But if you want a good starting point, you could do worse than starting with these projects:

TaskPyper is an early Python based project for working with TaskPaper files. It’s a good reference source but has not been developed since 2008.

The Python-TaskPaper project has been stagnant for 4 years but also provides a basis for working with TaskPaper documents.

SyncTasks is a Python based project for syncing TaskPaper with several other task management services, such as Google tasks.

Jerry Straton’s web display of TaskPaper is an interesting predecessor to other browser based implementations.

Folding for TaskPaper generates an HTML version of a TaskPaper document for use in a web page. It’s a clever way to share the progress of a development project.

TaskPaper+ looks to be a web app for working with TaskPaper files but feels like a mess. The GitHub page points to a Web site that is filled with pop-up ads. You should probably stay away.

TodoPaper is apparently a Windows alternative to TaskPaper. It looks like it is using the same syntax and reserved tags. I haven’t tried it but it would be my second option, after Sublime Text.

TaskPython-Web is a little python project for serving up TaskPaper files on a web server. This might be a lightweight way to go for interacting with TaskPaper files on an iPhone using Pythonista.

The Dropbox Taskpaper Editor looks like the holy grail but I was unable to get it functioning. It claims to be a web application that provides a full TaskPaper workflow and connects to your own Dropbox account. It requires an app key (which I generated). My intention was to get this running in Pythonista for iPhone or at least setup on my own web server. It’s certainly an impressive piece of work.

TodoFlow (a.k.a. Topy) is an incredible CLI implementation for TaskPaper files. It’s impressive for it’s support of the TaskPaper query syntax as well as the detail it generates at the bash prompt. But if that weren’t enough, there are Alfred and GeekTool extensions built off of it to provide a unified working environment all based on the TodoFlow scripts.

And just to show off, the developer “bevesce” includes a Pythonista version of the script.

JQuery.taskpaper is just what you think. It’s a JQuery, browser-based parser for TaskPaper formatted text.

Conclusion

There are a lot of smart people dedicated to the TaskPaper format and they have been for a long time.

Intellectual lock-in is hard to see while grinding away day after day with the same tool. Looking at what’s been done with this format over the years I see a huge variety of interpretations all built on some basic principles. TaskPaper is the idea, not the tool.

If you are interested in collaborating with some of the smart people that are using TaskPaper, contact them or me. I’ve gathered a few folks on Glassboard that are actively working on extending the TaskPaper toolkit. If you’re looking to help, you are most welcome to stop by.

References

There’s a lot of links in this post. Here’s a complete list of references:

To be fair, not even OmniFocus has feature parity across the platforms. There are still only context specific perspectives on iOS and they only recently added global search on the iPhone. ↩︎
Check out Sven’s list of tips and links for Reminders.app. ↩︎
Who can remember all of those perspectives they create, let alone all of the TextExpander shortcuts. ↩︎
There’s already plenty of OmniFocus export options available right now. ↩︎