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.

[zagortenay333]

This group syntax would only exist to allow for the natural comment sections that anybody would want to create when editing the todo file in an editor.

[karbassi]

@pablito1755 Let's take discussion of versioning to #6.

[pablito1755]

@zagortenay333 I've been mulling this over and sort of going in circles on the issue. Why do you think you need to re-order the file at all? It seems to me that the file is a database first and a document second. Granted, the database is much more easily editable by the user (hence it is a little like a document), but it is a database nevertheless. Consequently, when the user chooses to view tasks in some order, it isn't up to the client to re-order the database per the latest selected view. The client should simply display the tasks per the chosen view.

It seems to me that physically re-ordering the tasks cannot really work well when more than one project or context is assigned to it. The task can't be moved to multiple locations in the file. The client application would have to pick one, but which one is the right one?

This discussion brings up an interesting question: How far is the spec meant to go in mandating how clients manipulate the text files?

[zagortenay333]

The way I see it, the todo.txt file is a document first and a database second.

That's the whole point of the todo.txt spec; you have a human readable and editable text file so that if your client ever dies you are left with a perfectly functional file. It's a file meant to be edited in an editor as well as a special client.

I already said why I'm reordering the todo.txt file; it is the natural thing to do. A user will sort tasks in a particular manner for an extended period of time (especially if you client has decent sorting capabilities), so why wouldn't you want to benefit from a client and have it sort the todo file as well? The alternative is to just append tasks and that hampers readability.

It seems to me that physically re-ordering the tasks cannot really work well when more than one project or context is assigned to it. The task can't be moved to multiple locations in the file. The client application would have to pick one, but which one is the right one?

I don't understand what you mean by this. The right place is the one where the user put it into when they chose a sort order in their client.

[pablito1755]

@zagortenay333 When you spoke of sorting, I assumed you meant that the user could select a "Sort by project" or "Group by project" button/option which would re-order the tasks while grouping together the ones with the same project tags. However, if a given task has both the +ProjectA and +ProjectB tags, where does it get moved to physically? I figured that the same task can appear twice in the UI, but this can't happen in the file.

Have I misunderstood how your client app works?

[zagortenay333]

No, ofc the same task can't appear twice. I don't understand why you're talking about a particular sort mechanism? No matter what the sorting mechanism is, there will be issues with comments.

[mpcjanssen]

If you want the position of a task to become semantically important, this will have a big impact on parsing a todo file. If you like this approach, it already exists in the taskpaper format.

[ghost]

One way to handle a comment line would be for it to be attached to (to sort with) the task above it, e.g. the two lines sort as one and the ‘#’ alerts the program to this?

(A) take out trash @home +miscellaneous

remember both bins

[marcus-grant]

My humble two cents. I don't think comments that don't get parsed add value to the todo.txt format. It is valuable because it is a list of human editable tasks, which can be edited by a human in theoretically any editor. Maybe if it is decided that the format should have breaking changes, then maybe it's worth having one comment at the top specifying version number of the spec & file encoding.

Better if it is human editable by an editor that can sort lines alphabetically by the text on each line. Even better still if it is human editable with an editor capable of sorting by patterns and can filter by patterns. And best of all, all these capibilites can remain while having an app do the hard work of reading the contents and presenting the more complex relationships each task could have by linking related tags on each line.

Those comments have nothing to do with tasks that need to get done or what properties those tasks have. If you want things like saved filters, why not store that in a file that's specifically meant for storing client configuration? That information isn't useful to hand-editing the file. The user won't easily be able to read the file comments and use it recognize those relationships like compound filters without a computer parsing the file anyways.

And grouping the files by comment lines that seperate the tasks by spatially grouping them together means that the app using this file no longer sorts files by the important information like dates & priority. That's why the format is made the way it is, so even basic line sorting editors can sort by just ordering by the ASCII values of each line. With comments, that ordering disappears because # lines will always appear first and together, away from whatever tasks were under them before being sorted, killing the initial purpose of having the comments since now the line distance from a # character suddenly matters. That or you enforce the line position of each task and lose the ability to sort by priority and date.

Let the app do the complex grouping of tasks by related tags. That already exists with the tags available. You could do dependencies by implementing a id:123 tag on the parent, and the dependant task could have a dep:123 tag to link the dependency of the task on the line with dep:123 in it to the task on the line with id:123. You could group tasks with @contexts or +projects or something else entirely with key:value tags (e.g. group:a) for every line that has a group:a tag.

For comments in relation to a single task, I don't understand why you would do:

(A) take out trash @home +misc.
# remember both bins

when it's easier to read, and less complex to maintain to just edit the description of the task as soon as it occurs to you that both bins is important information for completing the task:

(A) take out trash, remember both bins @home +misc.

If more complex relationships are needed, I'd argue that splitting the file into seperate ones is a better approach, and that if this much importance needs to be placed on grouping over priority and dates, that maybe a todo list isn't the right metaphor for the system you're trying to create.

[zagortenay333]

Since filters don't have a standard format in todo.txt, they should be saved in a cache file by a client anyway.

Projects and contexts can already be saved in the todo.txt file easily using the h:1 extension (in fact, that's it's main purpose):

I really think the todo.txt file should be kept clean of any excessive metadata; other files can be used for that.

[adityabhaskar]

I've had a few user requests to add commenting support. After a brief exchange with them, I decided on supporting the '# ' (\^#\s+\)' pattern for comments in both the apps (Android, Chrome).

I just read through this discussion, and the discussion on ver 2.0 of the format. However, it seems that progress on both of these is stalled—been over 18 months since last update.

So, I have decided to go ahead and implement support for commenting in both my apps. The commenting support will be default off, and I will present user with a statement that other apps may not work well with the comments.

Just wanted to keep the community in loop, in case there's any feedback from users elsewhere.

[clach04]

I'm definitely interested in a comment line and # is as good as any. ; could work too.

In the mean time tools could agree on a standard in the existing spec, without need to add to it. See https://github.com/todotxt/todo.txt#additional-file-format-definitions for key/value and also https://github.com/todotxt/todo.txt/issues/8 there are some existing tools that will hide items with:

h:1
hide:1

SimpleTask for Android and https://github.com/schiessle/todotxt/blob/master/todo.actions.d/hide support h:1.