todo.txt syntax should include a "comment rule"

[karbassi]

From @polvoazul on September 27, 2016 6:17

I thing we should be able to add lines to todo.txt that are not going to be parsed as a task.
There are two main advantages to that:

1. This could be used to write comments, that could range from simple file section separators to editor (such as VIM) hints.
2. We could use these comments to store non-task data such as a list of projects, or saved filters, or anything else the imagination wants. It would be easy to extend the format by using this.

I suggest the following syntax:

Any line starting with "# " is a comment, and should not be treated as a task. It should not count towards task numbers and should be, by default, ignored by the clients.
Each comment can also have a tag, that must be written like this # {tag}:. This tag means that specific clients can take advantage of that comment to provide additional functionality. A suggestion of a tag would be proj, such that we could drop a line in our todo.txt:

# proj: +buyGuitar +researchNewMusic ...

and tools could keep this projects 'alive' even without any tasks assigned to them.

Something like:

# filter: arts="+music OR +art OR +buyGuitar"

could be used by a client to save a named filter. Possibilities are endless!

I suggest tags are kept very small to keep things uncluttered.
Clients that don't understand a tag must simply discard that line as a comment.

I think todo.txt format is great, but it lacks a little bit of flexibility and I think this extension would enable clients to implement features without breaking other clients!

What do you guys think?

Copied from original issue: todotxt/todo.txt-cli#190

[karbassi]

From @iansowinski on November 9, 2016 17:57

Just wanted to start the same issue here. I really would love some tools for commenting. With syntax highliting it's even easier to use todo.txt in text editor, and having comment rule for sorting list inside of text editor would be a big benefit.

[zagortenay333]

How is the positioning of the comments gonna be handled by clients? When the tasks get sorted, where do you put the comments?

[bram85]

This would break every client, so if implemented it would be todo.txt 2.0.

Named filters could be accomplished with aliases on the commandline, by creating an alias for each 'ls' invocation.

The way I handle notes is to add a note tag with an identifier, that matches an identifier in my notes system. Doing so is still compatible with the todo.txt format.

[pablito1755]

I definitely like the comment support idea and would like to see this included. However, as @bram85 mentions, it will break existing clients. Consequently, a version number tag should be included in the spec. to avoid such problems going forward. I suppose a comment/tag on the first line makes the most sense.

[karbassi]

Yes, any new spec changes will be discuss and versioned before anything is me final.

[pablito1755]

@karbassi Based on your answer, I may not have been clear. I think that along with the introduction of comments and tags, a standard tag (or even set of standard tags) should be defined. The "Version" tag would serve to tell clients the specification version of the todo.txt file. It would appear exactly once on the first line of the file :

# {Version:2.0}

# My non-project tasks
(A) 2000-01-01 First task @Work
x 2000-01-02 2000-01-01 Second task

# These tasks are for the Ace projet
(A) 2000-01-01 First Ace task +Ace @Home
x 2000-01-02 2000-01-01 Second Ace task +Ace @Phone

@zagortenay333 I hadn't noticed your comment until now and hadn't realized any clients did this. You're right, unlike multi-line tasks which naturally stay together, re-ordering comments could be more complex. Could you elaborate a bit on what your client does exactly? Could comment anchor tags work somehow?

[zagortenay333]

The issues is that if the user specifies a particular sort order (e.g., by priority) and adds a task via the client, then how am I supposed to write that to the todo.txt file? The natural thing I do is to simply overwrite the entire todo.txt file with the correct sort order and with the newly added task in the right place.
In general you can't use comments to delineate sections in your todo.txt file while at the same time adding new tasks via a client since the client can't tell where to put the task.

Also, why exactly would a user need comments in a todo file anyway? The only thing you would ever use them is to create sections in the file for easier reading:

# -------------------------------------
# Section 1
# -------------------------------------
(A) asdfadf
(A) asdfadf

# -------------------------------------
# Section 2
# -------------------------------------
(A) asdfadf

This can be solved by adding a group syntax to the todo.txt format. I.e., all tasks below a 'section header' are part of a group and the clients could then handle that stuff properly. Sort of like shallow subtasks, or like that multi-line syntax I proposed.

Btw, I don't like the idea of adding a version tag into the todo.txt file; that file should be kept clean of any metadata.

[zagortenay333]

For example using the syntax I proposed for multi-line tasks:

--- Triple `-` followed by some text starts a section
(A) asdf
(A) asdf
(A) asdf


--- Section 2
(A) asdf
(A) asdf


--- Section 3
(A) asdf
(A) asdf


--- (triple `-` alone closes the prev section if any)

(B) asdf
(B) asdf

[bram85]

Grouping can also be established with tags using the current syntax. You can use todo.sh ls or grep to filter out items from a certain group.

If needed, you can also sort items by group tag first, and then by priority.