search

todotxt / todo.txt

‼️ A complete primer on the whys and hows of todo.txt.
GNU General Public License v3.0
2.33k stars 102 forks source link

Ambiguity in the current todo.txt "spec" #70

Open camoz opened 2 years ago

camoz commented 2 years ago

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.

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.

clach04 commented 1 year ago

@camoz recommend closing this, looks like spec was updated to remove ambiguity on these two points.

camoz commented 1 year ago

@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.

clach04 commented 1 year ago

@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.

clach04 commented 1 year ago

@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!

drbogar commented 1 year ago

Which version is correct? There is still a contradiction in the description.

Do I understand that the text description is correct?

clach04 commented 1 year ago

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
drbogar commented 1 year ago

What if I also have a creation date? What if I also want to keep the priority of completed tasks?

callegar commented 1 year ago

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.

callegar commented 1 year ago

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?