todo.txt
todo.txt copied to clipboard
todotxt
Multi-line tasks
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
---
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
]
@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.
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
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.
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.
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.
@evanp that was already mentioned. That makes it impossible to paste text into the todo.txt file.
@zagortenay333 Why do you say that it makes it impossible to paste text?
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..
what about using the Markdown code block delimter (```) (that everyone is familiar with)
@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.
(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.
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.
me again. This time with a new delimiter that maintains single line compatibility - [CR][TAB]. (The [TAB] is for readability in case # 2 below.)
- 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
- A non-compliant/legacy implimentation will render
(A) @call 911 - first dial 9 - then 1 - and 1 - and hope for the best
- If you are at the *nix commandline, then piping through
trwill yield
$ grep '@call' todo.txt | tr '\r' '\n'
(A) @call 911
- first dial 9
- then 1
- and 1
- and hope for the best
Imo, block comments is the way to go here. I want to be able to paste in.
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.
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
<<<
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 :smiley:
+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
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)
The - indentation looks a lot like Markdown lists :)
Just goes to show great minds think alike. Lol :smiley:
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!)
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.
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?
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.
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.
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: https://github.com/todotxt/todo.txt/issues/2#issuecomment-332433209
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.