todotxt
Ambiguity in the current todo.txt "spec"
The current spec of the todo.txt format (I'm referring to the README.md in this repo) contains several ambiguities, as is shown by some issues, e.g.
- https://github.com/todotxt/todo.txt/issues/37
- https://github.com/todotxt/todo.txt/issues/26
It would greatly help to have a precise, unambiguous specification. This way, programs can interoperate better which each other. It should not be too hard to make one, since the format seems quite simple. IMO, the current situation is quite bad, the README.md gives a general overview about the todo.txt format, but there are things left unspecified and things that contradict each other.
This is of course a different issue from the issue talking about versioning.
@camoz recommend closing this, looks like spec was updated to remove ambiguity on these two points.
@clach04: Where was the spec updated? Since I created this issue there was no commit to this repo, and no activity on the issues I linked.
Also, the two mentioned issues were merely random examples to illustrate my point.
@camoz for number 2 see https://github.com/todotxt/todo.txt/blob/master/description.svg - I take it to be optional - EDIT see https://github.com/todotxt/todo.txt/issues/70#issuecomment-1249750530 this point is wrong!
for number 1 - completion rule 2 https://github.com/todotxt/todo.txt#rule-2-the-date-of-completion-appears-directly-after-the-x-separated-by-a-space which indicates priority is removed. NOTE this does mismatch with https://github.com/todotxt/todo.txt/blob/master/description.svg but I think the text version is definitive and clear (but that's my opinion 😉 )
I recommend checking the cli implementation https://github.com/todotxt/todo.txt-cli as it's seen as the reference one to check it's behavior.
Simpletask for Android (third party) does:
x date (A) date text
where (A) is the original priority so it's not really following the text spec properly.
I'm speculating that this changed in the spec after you posted your question, you can run annotate/blame to determine timeline.
@camoz lol, I may have proved your point about spec being unclear as I made a mistake when posting the above message! 😆
Completion date is required as per completion rule 2 https://github.com/todotxt/todo.txt#rule-2-the-date-of-completion-appears-directly-after-the-x-separated-by-a-space - my comment about about the svg showing optional is wrong!
Which version is correct? There is still a contradiction in the description.
- What is mandatory and what is not?
- According to the svg image, both the completion date and the creation date are optional, but if the completion date is specified, the creation date is mandatory.
- According to the text description, the completion date is mandatory and the creation date is optional.
- What is the correct order?
- The svg image shows the priority immediately after the completion mark.
- According to the text description, the priority is placed after the completion date and the creation date.
Do I understand that the text description is correct?
Which version is correct?
I believe text version is definitive, SVG is incorrect/not-strictly-correct.
Do I understand that the text description is correct?
That is my understanding, and matches the reference implementation:
mymachine:~/shell/todo.txt-cli$ todo add "test issue 70"
1 test issue 70
TODO: 1 added.
mymachine:~/shell/todo.txt-cli$ todo ls
1 test issue 70
--
TODO: 1 of 1 tasks shown
test issue 70
mymachine:~/shell/todo.txt-cli$ cat ~/todo.txt
test issue 70
mymachine:~/shell/todo.txt-cli$ todo done 1
1 x 2022-10-30 test issue 70
TODO: 1 marked as done.
x 2022-10-30 test issue 70
TODO: /home/pi/todo.txt archived.
mymachine:~/shell/todo.txt-cli$ todo ls
--
TODO: 0 of 0 tasks shown
mymachine:~/shell/todo.txt-cli$ cat ~/todo.txt
mymachine:~/shell/todo.txt-cli$ cat ~/done.txt
x 2022-10-30 test issue 70
mymachine:~/shell/todo.txt-cli$
Similar example with priority:
mymachine:~/shell/todo.txt-cli$ todo add "(A) important test issue 70"
1 (A) important test issue 70
TODO: 1 added.
mymachine:~/shell/todo.txt-cli$ todo ls
1 (A) important test issue 70
--
TODO: 1 of 1 tasks shown
mymachine:~/shell/todo.txt-cli$ cat ~/todo.txt
(A) important test issue 70
mymachine:~/shell/todo.txt-cli$ todo done 1
1 x 2022-10-30 important test issue 70
TODO: 1 marked as done.
x 2022-10-30 important test issue 70
TODO: /home/pi/todo.txt archived.
mymachine:~/shell/todo.txt-cli$ cat ~/done.txt
x 2022-10-30 test issue 70
x 2022-10-30 important test issue 70
What if I also have a creation date? What if I also want to keep the priority of completed tasks?
The description image underlines that creation date must be specified if completion date is, but then the very examples in this issue at https://github.com/todotxt/todo.txt/issues/70#issuecomment-1296405954 have a completion date with no creation date... sigh.
Also having two alternate ways to specify priority (as (...) and pri:...) seems weird, particularly given the fact that only one is allowed for completed tasks. How about non completed tasks? Can you use either one?