Multi-line tasks

[zagortenay333]

I really don't like the idea that a single task must be on one line only. It makes it very inflexible which is in stark contrast to the todo.txt is just a text file thing.

When a task gets longer it becomes unreadable, especially if you don't like using text wrapping in your editor.
Some examples:

(A) Figure out why this doesn't work: (code was just pasted in)
    for (let ... {
    }

(B) Fix this error message: (message was just pasted in)
    Assertion failed: 
    bla bla bla...

(C) This is a very simple bullet list consisting of things
    I don't want to be individual tasks:
    - asdf
    - asdf
    - asdf

(D) I think that word wrapping is a property of the text and not the
editor, so I want to add the word breaks in myself and not have
to rely on a editor/client to do it for me.

(E) 2000-01-01 2000-01-02 rec:12d-1m @asdf +qwerty
I can use the first line for the 'metadata' and keep the actual task
nice and clean.

There should be some way to add multi-line support in a simple, mostly backwards-compatible way. Off the top of my head (though this isn't exactly backwards-compatible):

(A) this is a single task
(B) this is another single task

---
(C) A task enclosed between lines only consisting of dashes
is treated as a
multi-line task.
---

---
(D) this is another
multi-line
task
---

(D) this is a single task
(D) this is a single task

---
(D) 2000-01-01 2001-01-01 rec:12d-1m +my_project

This is another long task I want to be split off into multiple
lines to make it readable. Maybe I might throw in some simple
bullet list:
  - asdf
  - asdf
  - asdf
---

[pablito1755]

It sounds to me like what you want is a task to support a body in addition to the existing "title". The current "description" part of the task is really more of a title or summary and I have found this to be a bit limiting on occasion (though not often). Adding any sort of length to the description quickly feels a little unwieldy in a text editor. If this were to go ahead, I think the current task line (first line) should remain the same for simplicity and consistency and a new marker on the very next line would indicate the start of the body and end with a corresponding "closing" tag.

Something like:

(D) 2000-01-01 2001-01-01 This is the summary rec:12d-1m +my_project
[
This is the first line of the body
This is the second line of the body
]

[zagortenay333]

@pablito1755 In my example, the first line does end up being the same.
I think the --- are much cleaner and more useful than [] when working in a text file.

[pablito1755]

I'm rather advocating the creation of a new body field which would be different to the existing description field. The existing description would remain as mandatory (though perhaps be renamed in the spec to the title or summary field). The new optional body field would start from the second line and end with the closing tag. All of your examples seem to suggest that the existing description field is still just a single field, but now spans multiple lines.

As for the start and end tags, I don't think it would be natural to have to specify the start tag before the first line when working in a text editor which is why I thought better to put it after the first line (when you actually decide you need it). That said, I've been rethinking this and a line continuance character might be a better way to go. I believe it is in VB that you specify the \ as the last character on the line to indicate to the compiler to effectively ignore the new line. In our case, the special character indicates that the task continues on the next line (the first instance marking the start of the body field). I think this might also lend itself well to linear parsing such that when the todo.sh finds the \ at the end of the line it prompts the user to continue entering text for the body field. So my earlier example would become (in the text file) :

(D) 2000-01-01 2001-01-01 This is the summary rec:12d-1m +my_project \
This is the first line of the body \
This is the second line of the body

[zagortenay333]

Ah, escaping the newline characters is an interesting idea. It would be almost perfectly backwards-compatible and easy to parse as well.

It is a little cumbersome to type though, and pasting text into your todo.txt file wouldn't work.

[pablito1755]

Yes, I suppose it is a bit cumbersome in an editor, but no matter the direction chosen there will a trade-off.

While on the topic of trade-offs, I note the following at the bottom of Gina's original spec. :

Philosophically, the todo.txt file format has two goals:

• The file contents should be human-readable without requiring any tools other than a plain text viewer or editor.
• A user can manipulate the file contents in a plain text editor in sensible, expected ways. For example, a text editor that can sort lines alphabetically should be able to sort your task list in a meaningful way.

These two goals are why, for example, lines start with priority and/or dates, so that they are easily sorted by priority or time, and completed items are marked with an x, which both sorts at the bottom of an alphabetical list and looks like a filled-in checkbox.

The introduction of multi-line tasks (discussed here) and comments (discussed in #1) violate the second bullet. I personally don't see this as a problem as I think the gain in new functionality outweighs the loss of auto-sort functionality for a few situations. The responsibility of sorting and filtering should lie with the clients.

[evanp]

What about if a line ends in \, the next line is appended? That's a common way to show continuation of a line, and doesn't require any other fanciness.

[zagortenay333]

@evanp that was already mentioned. That makes it impossible to paste text into the todo.txt file.

[pablito1755]

@zagortenay333 Why do you say that it makes it impossible to paste text?

[zagortenay333]

Well, not impossible, but if you have to then go in and escape all the lines you pasted it's pretty cumbersome. Don't you think? With the delimiters like --- you can just paste the stuff in without having to format it.

Escaping newlines is reeeeeally pretty elegant when it comes to parsing though..

[go2null]

what about using the Markdown code block delimter (```) (that everyone is familiar with)

[karbassi]

@go2null can you provide an example.

Moreover, from this point forward, if anyone who is proposing a new delimiter for this issue please include a couple of examples.

[go2null]

(A) @call 911
```
- first dial 9
- then 1
- and 1
- and hope for the best
```

In thinking about this, maybe the the shell heredoc style may be more appropriate as it avoids the need to delimit each line.

(A) +novel in the beginning <<END
Not so long ago
I couldn't do anything,
then I discovered todo.txt!
END

BTW, in my research for a simple text-based todo list app with multi-line support, I came across bug on the suckless website.

[go2null]

Ok, here is another comment. This time, I've had a bit more time to review and IMHO, multi-line addition to todo.txt should not break its core difference with the other apps out there - that is, that the entire task is on a single line.

Why? As I see it, as as it seems to have been envisioned (see @ pablito1755's quote above), todo.txt is a simple TODO manager, not a note-taking app. There are many note taking + task managers out there - see Org Mode which is available for basically all mobile and desktop platforms.

Why? Existing users. Take a look at this tutorial https://computers.tutsplus.com/tutorials/how-to-manage-your-tasks-with-todotxt--cms-20293

Why? It forces you to be succint.

Why? There is already a Notes addon.

[go2null]

me again. This time with a new delimiter that maintains single line compatibility - [CR][TAB]. (The [TAB] is for readability in case # 2 below.)

1. A compliant implimentation will replace the delimiter with [LF] ([CR][LF] on Windows).

(A) @call 911
- first dial 9
- then 1
- and 1
- and hope for the best

2. A non-compliant/legacy implimentation will render

(A) @call 911		- first dial 9		- then 1		- and 1		- and hope for the best

3. If you are at the *nix commandline, then piping through tr will yield

$ grep '@call' todo.txt | tr '\r' '\n'
(A) @call 911
	- first dial 9
	- then 1
	- and 1
	- and hope for the best

[zagortenay333]

Imo, block comments is the way to go here. I want to be able to paste in.

[mpcjanssen]

One big issue with all these proposals (except maybe the newline escaping one) is that it makes the parsing of tasks context sensitive. You can't parse line by line anymore and the correspondence 1 line 1 tasks is gone.

This is a big change and should not be made lightly IMO.

[zagortenay333]

@karbassi Any progress on this? Have you thought about this?

[zagortenay333]

Btw, instead of the --- delims I proposed above, a better one would be a git-like arrows delimiter:

>>>
Arrows would remove the ambiguity of not clearly seeing
where a task ends and where it begins.
<<<

>>>
asdfasdf
dasfa
<<<

Single line task.
Single line task.

>>>
asdasdf
asdfasdf
<<<

[mrbrahman]

Since todo.txt is meant for simple text editing, which is also easy on the eyes and not a full fledged language specification, I personally like the very first approach of indentation.

The other (breaking) solution would be to start each task with "-" or "*" or something like that as the very first character. Think about it -- TODO lists are generally bullet points! (say in a Word Document). So, just pick one character as the bullet and stick to it. I personally prefer "-". Now, if that becomes the rule, it simplifies everything else. If you want sub-bullets, then just indent or use a different bullet.

E.g.

#######
# TODO
#######
- This is my very first task
- (A) Figure out why this doesn't work: (code was just pasted in)
    for (let ... {
    }
- (C) This is a very simple bullet list consisting of things
    I don't want to be individual tasks:
    - asdf
    - asdf
    - asdf
- (B) Fix todo specs soon
    Lots of tasks ahead
    Many things to resolve 
- How about another task with sub tasks
* sub 1
* sub 2
* urgh! I should really indent this!
- This task has word wrapping. But with this solution, even
that is resolved! Even though this looks ugly :-(

#######
# DONE
#######
- x 2018-03-22 Call my best friend @phone

In fact this is how I've been manually managing my TODO.txt 😃

[varac]

+1 for indentation! I don't like the delimiters and indentation would be the most readable, i.e.

(A) Adopt todo.txt
    Wait for todo.txt multiline,
    try it and
    finally migrate from todoman to todo.txt!
(B) Do everything else

[go2null]

The - indentation looks a lot like Markdown lists :)

[elisdg]

I like the escaping newline idea.
The Advantage of [...] or {...} is, that one could better implement FOLDING in some tools (like vim)

(it would be better to have the opening brackets on the title-line)

[mrbrahman]

The - indentation looks a lot like Markdown lists :)

Just goes to show great minds think alike. Lol 😃

The thing is that a TODO list and Markdown list, are both "lists" in the first place. And what better way to represent items in a list than a bullet character!

(BTW, I think my good old TODO.txt file has been around for way longer than Markdown!)

[zagortenay333]

Yeah, indentation looks nice. Spaces or tabs though? ducks

[rdgarlo]

I have a work-around that I use for this. I believe that it complies with both of Gina's criterion:

Keep the entire task on one line of text in the file, but use a special character to represent each new line within the task. This doesn't look so pretty in a text editor, but it is still human-readable and it will still sort correctly. Applications could use the special characters to render the sub-tasks on separate lines. This method is also backwards-compatible. Example (using the pilcrow / ALT 20 ¶ character):

How it looks in the text file:
(A) 2018-08-07 Paint the house:¶ [x] Buy paint.¶ [ ] Mask trim.¶ [ ] Paint walls.¶ [ ] Clean up.

How it could look in an application:
(A) 2018-08-07 Paint the house:
[x] Buy paint.
[ ] Mask trim.
[ ] Paint walls.
[ ] Clean up.

[dessalines]

Multi line notes could effectively turn todo.txt into a notebook. This feature should've been added years ago. I personally like the --- as it would be simple to parse, and nothing would need to change for the current single line parsing.

How can I add this to the spec and get it merged so clients can start implementing it?

[ramblingjordan]

I was working on an alternative specification. It tries to address some of the missing functionality I'm looking for in my workflow.

The solution to this problem in the spec currently is that tasks start with a prefix of - [ ] a la GFM then continues until the next valid prefix.

See the spec details here: https://github.com/ramblingjordan/markdone/blob/master/spec/README.md

I would appreciate any notes. I have doubts about my ability to see it all the way through and am considering options such as making a converter that ports between the two specifications then use the tools already in existence with todo.txt.

[rdgarlo]

I have discovered an app that does what I want and more: https://github.com/QTodoTxt/QTodoTxt2/
It supports limited HTML tags, including <p>, <br>, and <li>, so I can format multi-line tasks to look just about any way I want in the app, but they are still human readable and sortable in a text editor. Tasks are still on one line in the text file, so they are backwards compatible and compliant with Gina's rules.

[go2null]

I have a work-around that I use for this. I believe that it complies with both of Gina's criterion:

Keep the entire task on one line of text in the file, but use a special character to represent each new line within the task. This doesn't look so pretty in a text editor, but it is still human-readable and it will still sort correctly. Applications could use the special characters to render the sub-tasks on separate lines. This method is also backwards-compatible. Example (using the pilcrow / ALT 20 ¶ character):

How it looks in the text file:
(A) 2018-08-07 Paint the house:¶ [x] Buy paint.¶ [ ] Mask trim.¶ [ ] Paint walls.¶ [ ] Clean up.

How it could look in an application:
(A) 2018-08-07 Paint the house:
[x] Buy paint.
[ ] Mask trim.
[ ] Paint walls.
[ ] Clean up.

@rdgarlo: see my post above: #2 (comment)

[dessalines]

That's exactly how you shouldn't use multiline notes.

Subtasks, or grouped tasks can be done via either contexts or tasks. In the above example you should make a tag for +paint_house and then add each of those tasks to it.

[rdgarlo]

The "+paint_house" project method doesn't work well for smaller/simpler projects. If the sub-tasks are all on separate lines, then if I add a task (i.e., different creation date) or change a priority, then the sub-tasks get separated when I sort the file. I also have to number the sub-tasks to keep them in the correct sort order, making the whole thing cluttered. Of course, tools exist to filter tasks by project, but the point of ToDo.txt is to be able to easily manage tasks in plain text.

For a simple project, I prefer this:
(A) 2018-08-07 Paint the house:
[x] Buy paint.
[ ] Mask trim.
[ ] Paint walls.
[ ] Clean up.

Rather than this:
(A) 2018-08-07 +paint_house 1.0 Paint the house :
(A) 2018-08-07 +paint_house 1.1 Buy paint.
(A) 2018-08-07 +paint_house 1.2 Mask trim.
(A) 2018-08-07 +paint_house 1.3 Paint walls.
(A) 2018-08-07 +paint_house 1.4 Clean up.

[dessalines]

You should be using clients like simpletask for android or qtodotxt for desktop that let you filter by tag / context. The point of the spec and common standards is for portability, and so many clients and platforms can use the standard. Otherwise why not just use a markdown file as your todo list like you did above.

Secondly you should be using priority correctly in the above example, and most clients will auto-sort it fine:

(A) 2018-08-07 +paint_house Paint the house
(A) 2018-08-07 +paint_house Mask trim.
(B) 2018-08-07 +paint_house Buy paint.

[rdgarlo]

I sometimes use SimpleTask and QToDoTxt.pyw. As I posted earlier, QToDoTxt parses selected HTML tags, so I can use <li>, <br> or similar tags in my text file and they will render as sub-tasks on separate lines in QToDoTxt, but are still human-readable and sort correctly in the text file. I consider this the "best of both worlds."

SimpleTask, QToDoTxt (and others) are great clients, but I want them to be optional to managing my ToDo list in any text editor on any platform. If I cross that bridge to a ToDo system that requires a client, then I will go to something that has the full functionality of the iCalenday / VTODO format (or similar).

[smichel17]

I also don't agree with adding multi-line support. It tries to make todo.txt into a fully fledged organizer, something it's not.

Multi-line support, dependencies.. A txt file is unstructured; it doesn't have the semantics to express these things. If you add those things, a regular plain text editor can't do sensible things to the file any more; you need a format-aware editor. At that point, you shouldn't use the .txt extension any more.

I'm not opposed to creating a different standard that attempts to share as much as possible with todo.txt, but adds support for multi-line tasks. In fact, there's a good chance I'd use it. However, I don't think that should be part of the todo.txt standard; it should be a fork that uses a different extension, like todo.md, if you go with markdown syntax (which would be my recommendation).

[dessalines]

@smichel17 Take a look at my PR. It's an optional, minimal extension that easily works with any plain text editor.

[smichel17]

@dessalines It works with any plain text editor, but doesn't work with existing tools specialized for todo.txt, which would probably fail parsing and mangle the multi-line task when writing. Also, if used frequently, it would clutter the file with a lot of --- lines.

A new format would not have to worry about legacy support, so it could use something like indentation or lack of a prefix to indicate multi-line tasks, which would be much more convenient, in my opinion. Again, I think multi-line support is a good idea, just not workable in todo.txt.

[chrisbeardy]

I agree that the biggest feature missing is the ability to add a lot more info to a line without the single line looking huge.

I only recently started using todo.txt, trying to migrate from org mode and trello for my personal stuff.

I started using the note addon. You can change the extension to .md too.

This is a great workaround for this issue while keeping consistency with the original format. It leaves todo.txt being a simple todo format and not trying to turn it into a larger project organiser. While giving you the option to add extra (multi-line) notes.

[cyevgeniy]

In my opinion, if a task cannot fit on one line, then it is not a task, or it is poorly formulated

[thomaspaulb]

For anyone who wants multiline tasks, you could also leave todo.txt be and switch to orgmode instead. I just did, and am pretty excited. It's an easy, flexible format to edit in your text editor and has great IOS (Beorg) and Android (Orgzly) apps developed for it.

[ts14ic]

I was under the impression, that todo.txt doesn't have and will never have multiline tasks by design.

With all tasks defined as 1 line I can press F9 in Sublime Text (sorts lines alphabetically) or whatever the button is in any text editor, and it will automatically sort all of the tasks according to priorities and put completed tasks in the bottom, because not a lot of words in English start with "x" or "z".
This trick would never work with multi-line tasks.

Maybe what's better, is having links inside single line tasks. The link can go to any file. For example to a different .todo.txt for sub-tasks or to an .md file for multi-line descriptions.
Doesn't even need spec modifications, and can be used straightaway, similar to how some zettelkasten editors open links by searching files with the same name as the link. By link, I mean something like See more at [another-file.todo.txt].

If linking is not attractive, then org-mode might really be the format you need, cause it can be as simple or as complex as you want, while remaining a plain text format as well.

update: Scrolled too fast. Noticed that there's already a comment here mentioning sorting. Well. I'll leave mine, because it suggests links as an alternative, and because this sorting feature is the only reason I'm using todo.txt.