Version 2.0.0 Spec

[karbassi]

For version 2.0.0 to be released, we need to complete

• [ ] Versioning specification - #6
• [ ] Specify file encoding - #10

[zagortenay333]

Any progress on any of this?

[heX16]

https://github.com/todotxt/todo.txt/issues/13

[laktak]

Do we really need a version?

JSON has no version number. No revisions to the JSON grammar are anticipated. If something has a 1.0, it will inevitably get a 1.1 and a 2.0, and everything is crap until it is 3.0. JSON is very stable. (Douglas Crockford)

todo.txt is already extensible with the key:value notation. I think having a stable format is more important than fixing some minor inconveniences.

[sanpii]

I comment here because, for me, the two pending issues may have the same solution¹: creating a metadata header:

# encoding: utf-8
# version: 2
First task

¹ Oops, it’s a standards proliferation variant, sorry.

[evanp]

Way more important to me to get the mobile clients fixed than to add a new version to the format

[nnako]

Reading through the issue texts so far, I saw of a couple of postings aiming in the same direction. So, for a broad usability of the v2.0 todo.txt file version, I would suggest the following requirements to be met (in addition to the first posting within this thread). With such a set of few but stable features, projects and personal management could greatly benefit:

• [ ] multi-line tasks - discussed in #2 [e.g. with special task-surrounding/concluding delimiters] -> separation of "title" and "body" possible -> detailed (and properly formatted) textual descriptions -> usage of standard markup languages (see below) -> values for tags should be possible in multi-line-mode as well -> insertion of text blocks easily possible -> optical separation of task-specific metadata and "real" content

• [ ] file-level comments - discussed in #1 and #6 [e.g. using the "#" character] -> format version specification possible (for checks within APPs) -> file encoding specification possible (for checks within APPs) -> subsequent chars until CR/LF will not be evaluated by APPs -> user can insert additioinal information invisible by APPs

• [ ] task-level comments [e.g. using specific tag "comment:"] -> additional information on task-level -> change history information (accumulating) possible -> date/time tracking of changes

• [ ] markup language support [e.g. MARKDOWN for bold, italics, itemization,...] -> well structured task descriptions possible -> easy import / export in other systems / tools

• [ ] multi-project management - mentioned in #13 [e.g. by specifying a tag "project:<prj1>/<prj2>"] [e.g. by specifying a "list" as "+<prj1>/<prj2>"] -> ability to assign a task to a specific sub-project -> all projects and sub-projects in ONE todo.txt file possible

• [ ] open but consequent usage of tags / values [e.g. keep ALL of them within the todo.txt file] -> stabile interchangability of each todo.txt file between multiple APPs possible -> possible management of tag usage on the todo.txt project page -> a tag which is not used by a particular APP should NOT be touched -> view settings like filtering, order,... not to be stored in todo.txt

I would think, there can be no way around an adjustment of already existing interfaces of developed APPs which use the current todo.txt file format. Especially, the following requirements would NOT be possible to meet anymore:

loss-free re-creation of the todo.txt file by a specific APP

• each APP would have to restrict itself to mere CHANGES of task-specific blocks within the todo.txt file
• it could otherwise be the case that tags not used by the particular APP get removed

sorting of tasks with a simple / ordinary plain text editor

• as multi-line task descriptions might not allow a line-based sort while preserving the blocks
• but maybe a concept of "escaping" line breaks via special characters might work

What do you think?

(and, by the way, is there a more practical way / tool to do this requirement discussion regarding v2? Something different than a linear discussion thread?)

[sanpii]

@nnako I’m agree with your proposals, but somes improvements are already listed for v3. It would be nice to release a quick v2 to allow versionning and work after on a v3 with more features.

[nnako]

@sanpii in my opinion, a MAJOR release (which is characterized by incrementing the leftmost digit of the version number) includes MAJOR changes like "interface changes" or "implementation language changes". MINOR releases (incrementing the 2nd digit of the version number) include features while keeping the old interfaces.

So, a good next step could be to identify "minor" and "major" features and then release a next MINOR CANDIDATE including these "minor" features. And at the same time create one MAJOR CANDIDATE including ALL the "interface changing" features in one go. Why work on two subsequent major releases and change the interface twice?

Why a "quick" v2? Why not a first "v1.x" and afterwards a sophisticated "v2.0"? These major version changes should be thought through very deeply, as they have the potential to spoil the entire project. I'd like to find a way of keeping the initial file format rules for todo.txt as much as possible while enhancing flexibility.

What do you think?

[sanpii]

What do you think?

Sounds great :smiley:

[Ekleog]

We were discussing in https://github.com/sanpii/todo-txt/issues/5, and there seems to be an issue about URLs and tags in the current specification. Should visit https://example.org be handled as task visit with tag (name: https, value: //example.org)? That's what the current specification seems to state, but I'd argue it's unexpected.

We discussed a few possible changes (@sanpii, @Nadrieril, feel free to correct me if I missed something):

• Consider tags whose value start with / are forbidden
• Blacklist some number of tag names (http, https, ftp, ftps, irc, ircs, mailto, smtp, smtps, imap, pop, pop3s, others?) and say they should be considered as part of the subject instead.

What do you think about it?

Also, the question of url:https://example.org arose. This is currently forbidden by the specification, as it states “Both key and value must consist of non-whitespace characters, which are not colons. Only one colon separates the key and value.”

Is there a reason why colons in the value aren't allowed? I can see the reason for forbidding them in the tag name (it would cause an ambiguous grammar otherwise), but I can see value in colons in the value, as shown by the example above. Did I miss the point of this ban?

[tomByrer]

IMHO todo.txt entries should be able to fit on 1 line; eg max length 80ish characters. I can see adding time to dates, declare file encoding since not everyone speaks English, maybe adding 1-2 currently often used tags.

But if all the other additions need to be made, perhaps JSON would be a better format? There is already great tooling available (JSON Schema validation, most languages have built in parcers, etc). Seems like this project is turning into wanting to be the output of JIRA or other huge project manager, not just jotting down notes in the command prompt.

(BTW, finding a JSON standard for TODO tasks is why I'm here.)

[zagortenay333]

@tomByrer What on earth.. JSON is terrible, universally and especially in this case. The todo.txt file has to be a simple human editable and readable file.. Think markdown.

The todo.txt should have been just an extension of markdown for tasks; that would have been ideal.

[varac]

@tomByrer I don't think json for todos is a bad idea but this would be a totally different project (todo.json ?). I like the simplicity of a textfile, that's the most important feature of todo.txt.

[heX16]

@tomByrer JSON is not the most successful format, which was born by chance. For machine is better msgpack.org and BSON. For people YAML and Markdown.

[tomByrer]

JSON wasn't by 'chance'; it IS JavaScript. Got popular because the other option at the time was XML, which is terrible.

Plan text can only hold so much info in 1 line in 'plain text' without becoming unreadable by humans. If simple text & human readability isn't a concern, then JSON or BSON or other binary format.. Otherwise, if you want to add much more than 1-2 more functions, then todo.md makes more sense than todo.txt

[heX16]

JSON wasn't by 'chance'; it IS JavaScript.

Frontend programmers started passing JS objects through the network and called it JSON. It became popular because it was supported in all browsers (unlike xml). Then this it has become standard. This is a spontaneous (accidental) emergence.

I do not know how to make the file compatible with JSON and at the same time keep it easy for people to modify it (manually). And I do not see any problems with parsing the current standard. Hence JSON is not suitable.

[tomByrer]

@heX16 sorry you seem misled https://en.wikipedia.org/wiki/JSON#History

JSON is fairly easy to edit by hand, but the point of a CLI / GUI interface is to avoid any direct manual manipulation. But JSON is FAR eaiser to edit than a 200 character line with estoric markup which todo.txt v2 & v3 are becomming.

@varac Yes I agree, but adding tons of extra features couteracts that simplicy.

I'll try out this GoLang program that uses JSON for abit: https://github.com/gammons/todolist

[Ekleog]

I personally much rather edit

(A) Say hello

to

{"priority":"A","text":"Say hello"}

especially as JSON is that fragile (no trailing comma, never forget the quotes…).

Anyway, I don't say there is no place for a todo.js project (actually I think it would be great to standardize something on JSON for those who want it). But, to me, it is completely out of the scope of todo.txt v2, and it is a completely different project.

A todo.txt v2 must at least try to not be breaking backward-compatibility too much, even though obviously there will have to be a few changes.

[andoresuperesu]

If we want both complexity and human readability we should much rather jump to yaml, which even includes referenciation; it should even allow templating within a simple "readable" file. However "readable" and "intelligible" tags are very subjective and are not up for discussion; those only reflect familiarity with specific formats or syntaxes. Plus the extension is not up for discussion, a todo.txt is the clear intent of this spec.

I agree with @Ekleog in that this is todo.txt; the world is open for todo.* projects to be created and those projects will most likely proliferate in the upcoming years. File encoding and versioning are the intent of this discussion, those are new to V2.

A single line starting with an octothorpe would solve both things:

• #todo.txt version=2.0 encoding=UTF-8

The omission of this line should fall back to v1 because it's the only other version in existence.

Please upvote, downvote or comment in reference to those items specifically, please create new issues for other additions.

[heX16]

New entity "comment" is not needed. Just add at first line "Todo.txt file. Version:2.0 Encoding:UTF-8".

[ghost]

I guess I am late to the party, but as for the suggestion of using JSON, maybe you should use TaskWarrior? They store your tasks in a JSON-like file and can be much more detailed than todo.txt files.

I like the current spec because, as I use a bunch of Unix-like systems, it's so simple that I already have the tools for manipulating a todo.txt file installed - awk(1), grep(1), sed(1) and friends - and I can use them in conjunction with a smartphone app if I want to.

IMHO todo.txt entries should be able to fit on 1 line; eg max length 80ish characters.

It doesn't even make sense. A line isn't limited to 80 chars. Of course, that's the default width for most terminals out there and it's a good practice to limit lines to 72 chars when writing e-mails and so and so, but almost every text editor can wrap lines, and, in my case, I can always use fold(1) if it becomes a problem.

As for the encoding, I would to push in favor of UTF-8 by default, but I don't have a strong position here.

Edit: fixed incomplete phrase.

[devmsv]

Yes, I think encoding should be UTF-8 by default: • if you only use ASCII chars it would be stored as ASCII • if you use other language (Spanish in my case) it's well supported (at least on *nix world)

and as @andresperezcera has told a single line with an octothorpe its the best approach (vim use this for file specific settings and its awesome)

[NicoVIII]

Is there a decision on this at the horizon?

My current impression is, that there are many ideas and opinions to develop it further but it is stuck at making a final decision on those issues.