TaskPaper 3.0 Preview (169)


I’ve made big changes in the way that TaskPaper’s text buffer keeps in sync with the outline model. Things seem to work for me, but beware bugs!

  1. Now when you manually expand an item all of that item’s children will display. Previously if a filter was active only the children matching the filter would display.

  2. Collapsed items are no longer automatically expanded when moving other items into them with Tab or the other arrow keys. In that case the parent item remains collapsed, but still displays the items that were just inserted. It’s a little hard to explain without seeing it, but key points are:

  • The underlying outline structure is updated and consistent just like before.
  • This change makes it easier to move folded items around without having things auto-expanding all over the place.

This release makes another big change to how focused projects are displayed. Now when you focus a project you can also see and edit the project title (like a few releases back). But unlike before you can now insert other projects above and below (as siblings) that focused projects. So now it works pretty much exactly as TaskPaper 2 did in that respect, but without requiring that the view is filtered by a search.

Other smaller changes include:

  • Show selected sidebar item in Window title.
  • Fixed View > Go Home menu item.
  • Italic text and different lead character for @search items in the sidebar.
  • Fixed bug where undoing delete of folded line would not add back children.
  • Updated to latest Sparkle and Paddle frameworks.
  • Added API for parsing TaskPaper date strings.
  • Added API for normalizing dates to TaskPaper style ISO strings.
  • Changed recommended API for grouping changes and undos when changing the outline. The old API remains in place, but I’ve removed documentation for it and instead encourage scriptures to use the new less error prone APIs.

Download TaskPaper 3 Preview


Really great. So much better! Thank you.

Of course, I’ve still managed to find a bug, but it’s pretty obscure.

In the uploaded file, select “header1/subhead1” with Select Branch and then Move Down past “header2”. The “header1/subhead1” item will (1) steal the subhead2 from header2 and (2) jump down past the “Sat” header.

This seems only to happen when i use (1) Select Branch on header1 and (2) header2 is folded. Dragging my cursor to select header1/subhead1 and the doing the Move Down past header2 doesn’t cause this behaviour.

But of course, Select Branch is something we want to use when we have a large unfolded item.

Anyway, something strange is going on with Select Branch.

test.taskpaper (73 Bytes)


Good catch, thanks. The difference is that “Select Branch” also selects the trailing newline and that’s when the bug showed up. Anyway I’ve got it fixed now for the next release.


Love this update so far.


Very nice update. Thanks!


Nice update! Thanks, Jesse.

What’s the new lead character for @searches? I’m seeing a … is this right?


Yes, that’s correct. Not sure it will be final, but what it brings to the table is that it stands out, but not too much. And S can stand for search. I’m not in love with it, but I also don’t hate it. I’m open to better ideas.


Hi Jesse,

I’m extremely unhappy with this change as filters on sub-items are now useless. For instance, I assign an @due tag to an item, which happens to be a sub-item of another @due item. I have a saved search, “Today”, which uses the following query:

@today or @due <=[d] today

Previously, this saved search would display only my items due today or prior. With this update, I now get a list of my top-level @due items, but when I expand any of the items, it shows the entire sub-hierarchy, regardless of whether the sub-items are due or not. What’s the point of using a filter if it shows non-filtered items?

I don’t understand why anyone would want it to behave this way, but I’d appreciate at least a preference setting to control this behavior.


Can you provide a simple example document to help me better understand the broken use case?

The new behavior should:

  1. Give the same exact initial search results.
  2. Allow you to expand items that previously would have been impossible to expand because they had no results.
  3. The only case where I guess this could be a problem (that I can think of) is if you:
  4. Search.
  5. Collapse some of your search results.
  6. Go back and expand those results again
  7. Does that explain your case?

I think generally this new approach is more flexible and forgiving. It doesn’t lock you into a search, instead you search, and then “browse” from that point forward. I find it much less constraining myself. Otherwise if I wanted to look into the children of some search result I would have to first cancel the search. (likely losing view of the original item in the process) Then go back and find that item without searching… and finally get to the children of that item.


Hi Jessie,

I was completely wrong, the filtering works fine and just as you described. It turns out, my issue is happening due to Taskmator’s date picker inserting alarm dates in a format that’s incompatible with TaskPaper’s date parser. Specifically, Taskmator inserts dates like this:

@alarm(2016-02-15, 08:00:40 AM)

The problem is the comma in between the date and the time. If I remove the comma, the task shows up in my today filtered view. I’m not sure if this is a problem with TaskPaper’s parser, or if I need to contact the Taskmator developer.


I’m thinking out loud here:

TaskPaper has two kinds of date syntax.

There’s the “input” syntax. Uses in the query language, and potentially in the future in other parts of TaskPaper. It’s goal is to quickly and directly allow you to specify a date and time using “some” natural language terms. For example “today”, “next week”, “Monday 10pm”, etc.

The other date syntax is “ISO” which TaskPaper uses (will use increasingly going forward) as the format used to “store” dates. For example:

  • 2016/02/16
  • 2016/02/16 04:59
  • 2016/02/16 04:59:23

I “think” those dates all conform to the ISO date/time standard. Often ISO date/times are more formally separated by a “T”, but I think that using a space is also still a valid ISO date/time format. The nice thing about conforming to that standard is that it’s a standard… making it easy for others to read and work with TaskPaper formatted dates.

Anyway, I think going with ISO in the TaskPaper syntax makes the TaskPaper format more universal and interoperable, at the expense of some readability. The comma isn’t such a big issue, but I think the ISO format also requires 24 hour time, instead of using AM/PM, which can be hard to get used to.

The alternative is to make the date parser more forgiving here…, but if I do that the standard goes away and it becomes harder in the future to work with TaskPaper dates.

With all that said right now my preference would be to ask the TaskMator developer to give an option (or just default to) outputting ISO date times. I think longer term the editor could help make these ISO formatted dates easier to read (provide a localized rendering of them), better to just use the ISO standard now in the underlying format.


I’ll email him and ask him to read this thread.

Regarding the input syntax, do you intend to have TaskPaper automatically convert dates like “Next Tuesday” into an absolute date in ISO syntax? Presently, it seems to just store whatever you enter literally.


I don’t think automatically, but yes I intend to add some way to do this. In the most recent release I added an API for converting dates to TaskPaper’s standard ISO format: http://guide.taskpaper.com/DateTime.html. I’ll create some sort of command to perform this translation when needed. Just not sure if there’s a better way to do it then just transforming the selected text.


OK, but why the need to execute a separate command to translate the date? Why not just have it do the translation on the fly? This would be much more convenient and you’d avoid having to remember to execute the command each time. Entering a date like “Next Tuesday” would be useless without the translation, because the task would never become due. Same situation with dates like “Tomorrow” or “Today +5”, etc… None of them will ever become due, so I can’t imagine any user wanting to store relative dates.


I’m not sure what the final sequence will look like, but I think it won’t be that TaskPaper just recognizes “tomorrow” and automatically replaces it with a date. That sort of automation, even if correct 90% of the time, is a royal pain I think the other 10%. I think maybe better would be a special “Insert Date” command that would popup a separate input context where you could type “tomorrow” and then when you “Enter” it would insert an ISO date. Or something along those lines.


Doing it in a separate step, as you’re proposing, would make sense if it entered the entire string for you, including the @due tag, parenthesis, etc… Thus, the inconvenience of having to use a separate command would be offset by the convenience of not having to type @due, etc… It would be a “Set Due Date” command. You could also do a separate one for “Set Start Date”, using a @start tag.

Having these types of macros built-in to TP would help to bridge the gap between the simplicity / flexibility of TP and the scheduling power of something like OmniFocus. The biggest hurdle for me, in moving away from these elaborate planning systems (I tried every single one of them!) , was giving up stuff like popup calendars, start/due dates, etc… Now, with the addition of date support in TP, we can have our cake and eat it too. You just need to make these features a little more convenient and accessible, so people don’t have to remember complex syntax and can avoid typos, potentially resulting in missed due dates.


I know a preference for this is not suitable in the preferences panel within the app, that you try to keep simple. But, I’d really like to test some alternatives. Would it be possible to provide a hidden preference for this lead character? Something like:
defaults write com.hogbaysoftware.TaskPaper3 SidebarSearchLeadCharacter '–'

Small visual annoyances tend to become greater glitches through my designer-OCD lens. I think things got worse after the 🔍. The :: was a little strange, but the is stranger. I can only see a coin there! I think that the emoji is naturally interpreted as a common icon, and the S-coin character not. So the stands out much more than the 🔍.

Besides of that, I’d really like to see more of these hidden preferences in TaskPaper. They can provide a broader range of customization for “advanced users” without complicating thing for newcomers.