jotaen/xit

A plain-text file format for todos and check lists

[x]it!

A plain-text file format for todos and check lists.

• 👉 Learn how [x]it! works
• 💡 Read the file specification
• 💬 Discuss ideas and questions
• 🛠 Share an [x]it! tool you made

xit's Issues

Make technical definitions more precise

There should be more precise definitions for some of the (technical) terms that are used in the spec, e.g.:

• What is a blank line? I.e. what characters is it allowed to consist of exactly
• What is meant by letter (for tags)?
• What is meant by punctuation?

I think it’s probably best to base these definitions on unicode categories.

Support more checkbox statuses

Apart from the currently supported statuses [ ] (open), [x] (checked), [@] (ongoing), and [~] (obsolete), there might be more useful ones.

I think the overall number of statuses should be limited, just so that they can still be memorized relatively easily. To me, there shouldn’t be more than 5 or 6 overall, which – next to the existing ones – would leave room for 1–2 more.

The purpose of this issue is to collect and maintain an overview of potential candidates.

Purpose	Symbol Ideas
“unclear”, “in question”	[?]	#34
“paused”, “on hold”	[.]	#42

Note: the requirements for a symbol are:

• It should be somewhat self-explanatory
• It should be language-agnostic, so it should be a symbol, not e.g. the first letter of an English word
• If ever possible, it should be an ASCII character, to ensure that it’s easy to type on every keyboard
• There should only be one canonical symbol per status, so no “aliases”

Group descriptions below titles

As discussed here, an item group could have an additional, optional description underneath the headline, like so:

MONDAY
Today, I need to really need to take care
of the remaining tasks from last week!
[ ] File tax report
[ ] Wash up dishes
[ ] Watch new Netflix show

It would basically work like this:

• First line is the headline (as it is right now)
• Subsequent lines are interpreted to be group description
• First item ends the group description

Things that need to be decided and specified:

• Can the group description contain tags?
  • If so, they would have to implicitly apply to all items in that group.
• Does there have to be any restriction regarding the text itself? E.g.:
  • Like in titles, a line cannot start with [, to avoid ambiguity or confusion with items
  • Can lines start with whitespace, i.e. can they be “indented”? Could this cause problems?
  • Obviously, lines cannot be blank, because that would start a new group
• Like for descriptions, I wouldn’t want to introduce special syntax for text formatting or links.

First stable version

The file format is currently in draft/RFC, but eventually there should be the release of a first stable version.

The plan is this:

1. During the current draft/RFC period, verify the basic idea and clarify details in the spec. But don’t make any major additions, unless absolutely necessary.
2. Once the spec seems solid, release the first version. I’d expect this to happen within a few weeks to months. That should be enough time to let things sink in and solidify. I guess time will tell.
3. From that basis, spec changes or additions can be discussed and released one by one. Candidates would be:
   • #2
   • #10

This is cool!

Great job on this, love what you're doing here.

I wonder if I can convince my favorite todo app, Things, to adopt your format and make their lists more portable.

Feel free to close this issue :)

Provide thorough test data

For tools or editor plugins it would be useful to have a thorough test file, to check whether all rules and edge-cases are handled properly.

I’ve already shared something in #6, but that could be more thorough and better structured.

It’s probably best to provide a copy-able file on the website, and then have separate annotations for more details.

Consider supporting nesting

I recently tried to convert my existing plaintext TODO list which uses Github's Markdown format for showing checkboxes, combined with indentation for nesting sub-items, for example:

- [x] Item 1
  - [x] Subitem 1
  - [ ] Subitem 2

Which is nicely rendered by Github:

• Item 1
  • Subitem 1
  • Subitem 2

I don't mind if [x]it! doesn't prioritize feature parity with Github Markdown checkboxes like the example, but it would be nice if nested lists were supported. Once I remove the hyphens, here's how this list gets formatted in VSCode using the xit extension:

As you can see, it doesn't show nested items as complete even when they are marked with [x]

For tags, switch from Unicode “letter” to “alphabetic” for allowed characters?

A “letter” (the allowed character class for tags) is currently defined as “a character from the Unicode Letter category (L)”.

This comment suggests that it would be better to use the “alphabetic” category instead, which appears to be a superset of “letter”.

A brief Google search didn’t yield too much substantial insight into the practical differences between the two categories, so I need to look into this more closely.

VSCode Extension

A VSCode extension would be veeeery nice to have!

Rephrase rules for characters that may appear around tags or due dates

The current rules for what characters are allowed to appear around tags and due dates read somewhat complicated or obscure to me:

The description MAY contain the following tokens:

• One due date
• Any number of tags

These tokens MUST be surrounded by whitespace or punctuation, except for such punctuation which the tokens themselves can consist of.

At the end of the day, the underlying goal is to have simple and intuitive rules, that allow tags and due dates to appear naturally in the flow of a sentence, e.g.:

• [ ] Do taxes (#work, #finances)
• [ ] Call #Mike: discuss weekend plans
• [ ] Paint fence -> 2022-04-18, Larry comes over to help
• [ ] Change tires (-> 2022-05-02)

I suppose this can be explained in a more straightforward way.

Suggestions for including xit markup in "TODO" or "FIXME" code comments?

I love the idea of xit and was wondering if anyone is using it to formalize TODO and FIXME style markup in code comments? Many of us probably have code this like:

// TODO: improve name of variable
const myVar = X();

// FIXME: implement this
function empty() {}

It would be great to include xit markup "inline" with the code and then be able to use parsers to pull that code out for other purposes. This might be a good feature to consider for xit specification. An obvious model might be something like the following:

// TODO: [ ] This is an open item
const myVar = X();

// TODO: [x] This is a checked item      -- probably would never see this since finished items are usually removed
// TODO: [@] This is an ongoing item
// TODO: [~] This is an obsolete item
// FIXME: [ ] This is an open item

Alternatively, specifically include (xit) for parsers?

// TODO(xit): [ ] This is an open item
const myVar = X();

// TODO(xit): [x] This is a checked item
// TODO(xit): [@] This is an ongoing item
// TODO(xit): [~] This is an obsolete item
// FIXME(xit): [x] This is a checked item

Reconsider syntax rules for empty/absent tag values

Currently, the (draft!) spec says about tag values:

A tag MUST start with the hash character (#), followed by one or more characters for the name of the tag. There MAY follow an equals sign (=) along with one or more characters for the value of the tag.

Based on this, the following things cannot be written:

• #tag=
• #tag=""
• #tag=''

However, what does it mean that this cannot be written? Shall either the whole tag or the value part be marked as invalid? Or just be ignored?

On the one hand, #tag= etc. doesn’t have any “meaning”; on the other hand, it also doesn’t do any harm (as far as I see). So I suppose it eventually comes down to the question which is more convenient for both users and tool-builders.

Functionality-wise, these cases should behave the same as writing #tag, so absent tag value is the same as empty tag value.

1.) Allow tag values to be empty

One option would be to adjust the spec, to allow tag values to be empty:

There MAY follow an equals sign (=) along with any number of characters for the value of the tag.

It then should also be clarified that empty tag value must be interpreted the same as absent tag value.

Add Creation and completion dates

This looks very cool! I currently use todo.txt and im thinking to change to this.
Maybe the format can have optional creation and completion dates for items?

A way that I think this can be done is in the first line of a long description (or the second line of the item) like this:

[ ] Paint the room
Created: 2023-02-01 Completed: 2023-03-04
More description if needed

It would probably be neater to choose some kind of symbol or abbreviation to denote Created and Completed instead of using the words.

Consider `[?]` items...

Sometimes I write down something that I might need to do in the future, pending outcomes outside of my influence.

This is essentially a pre-flag for [ ] items which are more likely than average to become [~] items.