description of todo.txt format in plain text

[rachmadaniHaryono]

maybe keep the image?

i sometime forget the rule/format and but always remember the image.

[waldyrious]

maybe keep the image?

@rachmadaniHaryono isn't the image redundant with the text-based diagram? They contain exactly the same content :thinking:

Compare the image:

...and the text-based diagram:

┌─────────────────── Optional - Marks completion 
│  ┌──────────────── Optional - Marks priority 
│  │      ┌─────────────── Optional - Completion date 
│  │      │          ┌──── Optional - Creation date
│  │      │          │     (must be specified if completion date is)
│  │      │          │        ┌─── Mandatory - Description
│  │      │          │        │    Tags (optional) can be placed anywhere within it.
│  │  ┌───┴────┐ ┌───┴────┐ ┌─┴────────────────────────────────────────────────────┐
x (A) 2016-05-20 2016-04-30 measure space for +chapelShelving @chapel due:2016-05-30
                                              └──────┬──────┘ └──┬──┘ └──────┬─────┘       
                                    project tag ─────┘           │           │
                                    context tag ─────────────────┘           │
                                    arbitrary key-value tag ─────────────────┘

[rachmadaniHaryono]

i thought about it once again and you are correct. if the target is to have a text-only format, it is the correct way to go. so just ignore my last comment

---

other than that

• please add the top bracket to x and (A).
• should the top text be left-aligned just like the bottom text?
• does the image will be deleted?

[dinosv]

i thought about it once again and you are correct. if the target is to have a text-only format, it is the correct way to go. so just ignore my last comment

other than that

* please add the top bracket to `x` and `(A)`.

* should the top text be left-aligned just like the bottom text?

* does the image will be deleted?

Thanks, @rachmadaniHaryono! Nice suggestions. I put a new bracket on priority and modified the text alignment. I do not know if putting a bracket over x could be done without changing too much the rest of the block or using some special Unicode character.

About the image, I guess it can be decided by the repository owner. My original idea was to have a file that could be parsed through Pandoc in order to produce and print a txt output.

Thanks everyone, specially @waldyrious for the changes.

[waldyrious]

@dinosv any thoughts about removing trailing whitespace (suggested at the end of this comment) and replacing "special" with "arbitrary" (suggested in this comment)?

[dinosv]

@waldyrious yes, sure. Do you mean something like this?

┌───────────────────────────────── Optional - Marks completion 
│  ┌────────────────────────────── Optional - Marks priority 
│  │   ┌────────────────────────── Optional - Completion date 
│  │   │          ┌─────────────── Optional - Creation date
│  │   │          │                (must be specified if completion date is)
│  │   │          │           ┌─── Mandatory - Description
│  │   │          │           │    Tags (optional) can be placed anywhere within it
│ ┌┴┐ ┌┴───────┐ ┌┴───────┐ ┌─┴────────────────────────────────────────────────────┐
x (A) 2016-05-20 2016-04-30 measure space for +chapelShelving @chapel due:2016-05-30
                                              └────────────┬┘ └────┬┘ └───────────┬┘       
                                   project tag ────────────┘       │              │
                                   context tag ────────────────────┘              │
                                   special key-value tag ─────────────────────────┘

About the change from special to arbitrary, I agree in the view of the "standard" of todotxt, because any tag with key:value format is arbitrary, but some implementations have nested some of those tags (like due: for example), so they are not arbitrary anymore. I would leave that to the developers as well, because it also involves modifying the last section to clarify this aspect.

[waldyrious]

yes, sure. Do you mean something like this?

Sorry, I don't understand what you changed in that snippet :sweat_smile: there's a single space character at the end of the first three lines of the snippet, and seven space characters at the end of the 10th line.

About the change from special to arbitrary, I agree in the view of the "standard" of todotxt, because any tag with key:value format is arbitrary, but some implementations have nested some of those tags (like due: for example), so they are not arbitrary anymore.

I understand your point, but even if some implementations do assign special meaning to specific key-value tags, those implementations still (should) support arbitrary such tags with prefixes they don't recognize, lest they violate the spec of what a valid todo.txt line can be.

That said, I can see that one could argue that such tags only make sense in the context of an implementation that does recognize the specific key prefix, so I guess it's a matter of whether we want to describe what the tags are in terms of formal specification, vs. how they are (expected to be) used in practice. A reasonable argument can be made for either position, so I'm OK with whatever choice you make.

[dinosv]

Sorry, I don't understand what you changed in that snippet sweat_smile there's a single space character at the end of the first three lines of the snippet, and seven space characters at the end of the 10th line.

Sorry! Lost in translation! Now I see that you referred to the end-of-line whitespace. I deleted it.

About the change from special to arbitrary, I agree in the view of the "standard" of todotxt, because any tag with key:value format is arbitrary, but some implementations have nested some of those tags (like due: for example), so they are not arbitrary anymore.

I understand your point, but even if some implementations do assign special meaning to specific key-value tags, those implementations still (should) support arbitrary such tags with prefixes they don't recognize, lest they violate the spec of what a valid todo.txt line can be.

That said, I can see that one could argue that such tags only make sense in the context of an implementation that does recognize the specific key prefix, so I guess it's a matter of whether we want to describe what the tags are in terms of formal specification, vs. how they are (expected to be) used in practice. A reasonable argument can be made for either position, so I'm OK with whatever choice you make.

Although I agree with you on this now, maybe it is best to stick with special for now. I suppose @karbassi can give us his insight on this.