Subtasks / Subitems / Nesting

[jotaen]

Items could contain subtasks, e.g.

[ ] This is a big one
    [ ] Part 1
    [ ] Part 2

The nesting could in theory be arbitrary.

There are legitimate use cases for this, and it’s also a natural thing to do. On the other hand, it might also create some complications:

• There can be conflicting state, for example: what happens if the parent item is checked, but the children are still open? Or the other way around? If all children are checked, shouldn’t that “automatically” resolve the parent? What if the parent has a closer due date than the children? And so on. While decision could be made for any of these corner cases, it might still feel strange in practice.
• The parsing becomes more complex. I’ve fiddled around with this idea in the Sublime Package, but I’m not sure this would even be possible to accurately implement with Sublimes’ syntax highlighting engine. The same problem might exist in other editors. I’d need to look more into that, however.

In the end, it’s really a cost-benefit question, whether or not this is a worthwhile addition.

I’m going to experiment with this in the Sublime Text Package, to get a better feeling for these questions. If anyone else has thoughts or experiences, please do share them here.

[mzur]

I use a very similar syntax in Sublime for my TODOs and I'd love to switch to [x]it once the Sublime package is out. But I do also use subtasks as described here all the time, so I wanted to add my two cents regarding your first bullet point: I'd just leave it up to the "user" to maintain consistency in the file. There is no need for a complex specification in this regard, as there is no way to enforce it, really. Users can do with their text files whatever works best for them.

[jotaen]

Thanks for the feedback. My main concerns with this were two-fold:

• Trying to avoid confusion for users, as it’s not clear enough to me what peoples’ expectation would be for these conflicting scenarios mentioned above.
• I’m asking myself whether the spec should cover these scenarios, so that tools (should there ever be more than the Sublime plugin…) behave consistently. It might be weird if one tool automatically checked all sub-items when checking the parent, and the other doesn’t. So maybe the spec should at least make a recommendation for tools how to behave in these cases.

I agree that it’s not good to limit the flexibility without there being a strong reason for it, and I’m currently positive that a good solution can be found for making the subtasks happen.

[ryanolsonx]

In my opinion, a tool shouldn't change todo items for the user. It should be up to the user to keep things consistent (due dates / sub items / todo items). As the owner of the plain text file, that's what I'd be 100% OK with.

[jotaen]

@mzur oh by the way, the Sublime package is available now.

[jotaen]

Additional edge-cases / questions that came to my mind:

1.)

[ ] Parent with ...
    multiline description
    [ ] Child item
    [ ] Child item with ...
        another description line
    Can a description line appear here?

I would tend to say no, because it might become unclear then where the last line belongs to. I also think it might complicate the implementation of parsers, because the data structure of child items would be less stringent, if child-items and description can be interspersed.

2.)

[ ] Parent
        [ ] Is this allowed? (I.e. “skipping” levels)

I’d also tend to say no, because it’s hard to say how this is supposed to be interpreted.

3.)

Semi-related, the subsequent lines of a description might currently (!) also have additional preceding whitespace:

[ ] Parent with a ...
               multiline description
    [ ] And a child item

But that of course could also be debated, whether subsequent description lines must start with non-whitespace characters after the indentation sequence. I’m not sure such a restriction for descriptions would really be necessary or beneficial, though – I tend to doubt it.

[jotaen]

I mean for now, I don't think we're gonna figure out what to do exactly about nested structures without having some implementation first.

That’s true, although I think it’s valuable to somewhat talk it through beforehand, before someone sets out and invests time and effort into implementing something.

I’m probably going to open a WIP branch in the Sublime Text Package at some point, to toy around with the nesting and get a better feeling for it – at least as far as the syntax-highlighting side-of-things is concerned.

[delfiin]

I will leave nesting alone completely I think until there is consensus.

[c-ehrlich]

If all items were on their own, then querying for #garden would only return the first item (i.e. the parent).

Upon second reflection I agree with this, and the general need for a clear hierarchy of items.

One thing to think about is whether a parser should define a "level" as being 4 spaces, or just any amount of indentation that's more than the nearest parent - for example the below is functioning python code, but I'm not sure whether or not it's good to have the equivalent of something like that be valid [x]it.

def hello_hello_hello_world():
           for x in range(3):
            print('hello')
           print('world')
hello_hello_hello_world();

Of course docs, editor plugins, etc. should encourage 'good' syntax, but how lenient do you want to be on parsing 'bad' syntax? Personally as someone interested in using this, i don't have a strong opinion in either direction.

[jotaen]

The original idea with [x]it! is that it’s basically a data format for check lists (which todo lists also fall under) in plain text, which is pleasant to read and to write. In that respect, .xit files are not meant to be free-form documents that happen to contain check box items here and there, but it’s rather that the check box items are first-class citizens, and the .xit file is about the check lists primarily.

The spirit is similar to e.g. the plain-text accounting formats (h)ledger or beancount, or my other project klog (for time tracking in plain text), or of course in some way also todo.txt.

That being said, it’s probably better to lean on the strict side of things, as far as the formatting is concerned. But of course there is room for “common sense”, so for example:

• If a document was indented with tabs instead of 4 spaces, then a tool could still decide to accept it, since it can be parsed unambiguously. It would be nice, though, if the tool would tell the user: “hey, your indentation style is not right for the file format, shall I fix that for you?”
• If someone wrote 6.), the file should probably be rejected, or at least the respective section should be marked as invalid. That’s because the document structure cannot be understood, and in that case I’d argue it’s better to raise an error than to silently try to make guesses.

Figure 2.) (the [x]it!-equivalent to your Python sample) is more tricky. A tool/interpreter could make a guess here, but it might be just wrong. (Think: maybe there was a sub-parent item in between, which the user had deleted, and now the 2nd-degree-child-item is dangling.)

I generally think that on the one hand, users shouldn’t be bothered with overly (or even unnecessarily) strict rules, but on the other hand the structure needs to be unambiguous, and users should have reasonable (!) incentives to express themselves clearly.

[delfiin]

Think: maybe there was a sub-parent item in between, which the user had deleted, and now the 2nd-degree-child-item is dangling.
With the right tooling that wouldn't be a problem. i.e. the user wouldn't even be able to do that without the parser immediately saying "hey you left an orphan".

[majkinetor]

Editor plugins could use this to enforce some dependencies. For example

1. When Sub-subtask 2.1 is completed, it could mark parents with @
2. When date is added to subtask, it could add maximum subtask date to parents
3. It should not allow completion of parents if there are open children

Example of first rule:

[@] Big task 
    [@] Subtask 1.1
        [x] Sub-subtask 2.1
        [ ] Sub-subtask 2.2
    [ ] Subtask 1.2
[ ] Small task

[ernstki]

When Sub-subtask 2.1 is completed, it could mark parents with @

This is a great suggestion, and I'd recommend [/] for partially-completed tasks rather than @.

If I were filling out a paper checklist, and wanted to indicate an in-progress or partially-completed step, I would diagonal-stroke through the box. Then "✗" the box when it's completely done.

I don't know who I learned this from, but it would seem to be a real-world convention that already exists.

Edit: Oh bother, I just realized [@] was already written into the spec. Never mind!

[jotaen]

I had also considered [/] initially for ongoing items, but in the end I liked [@] slightly better: a) because I found it more self-explanatory (“I’m working on/at/@ this”), and b) because it’s visually a bit more distinct. I also thought, [/] could also be interpreted as “partially done”, which has a slightly different notion than “ongoing”.

I think all symbols leave room for (mis-)interpretation, so unfortunately it’s tricky to choose them so that they are universal and unambiguous.

Edit: Oh bother, I just realized [@] was already written into the spec. Never mind!

The spec is a working draft right now, so I’m open to reconsidering everything what’s in there. (Which is now easier than at a later point.) That being said, I think it’s a good feedback to see how other people interpret things, and to then see whether or what to adjust.

[gerardp]

Items could contain subtasks, e.g.

[ ] This is a big one
    [ ] Part 1
    [ ] Part 2

The nesting could in theory be arbitrary.

There are legitimate use cases for this, and it’s also a natural thing to do. On the other hand, it might also create some complications:

* There can be conflicting state, for example: what happens if the parent item is checked, but the children are still open? Or the other way around? If all children are checked, shouldn’t that “automatically” resolve the parent? What if the parent has a closer due date than the children? And so on. While decision could be made for any of these corner cases, it might still feel strange in practice.

* The parsing becomes more complex. I’ve fiddled around with this idea in the Sublime Package, but I’m not sure this would even be possible to accurately implement with Sublimes’ syntax highlighting engine. The same problem might exist in other editors. I’d need to look more into that, however.

In the end, it’s really a cost-benefit question, whether or not this is a worthwhile addition.

I’m going to experiment with this in the Sublime Text Package, to get a better feeling for these questions. If anyone else has thoughts or experiences, please do share them here.

You can try plainTasks, which is a very similar project, to see how they have solved it.
https://github.com/aziz/PlainTasks

[khimaros]

syntax highlighting aside, i have a modified version of the stage_left library which supports sub-tasks. is that sufficient to allow this design to progress?