Ability to add free/more text in the file

[jotaen]

Currently, the spec only allows to add text as titles or item descriptions. But what about something like:

Some text
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Suspendisse efficitur lacinia nunc, vel gravida mi. Morbi
vel tellus ac massa condimentum vulputate. Nulla rhoncus
lacinia purus, sit amet luctus turpis. Etiam efficitur
convallis massa.

Some todos
[ ] Item 1
[ ] Item 2

Another possibility would be to at least allow for having more descriptive text underneath the headline, like:

MONDAY
Today I really need to focus a bit,
to not fall behind on my todos.
[ ] Item 1
[ ] Item 2

So basically the first line is the headline, the subsequent lines are a block description, an then come the items.

If the latter was possible, the former might be possible automatically, because groups can already be empty. Only caveat would be that the first line of the paragraph is treated as headline, and might be formatted differently.

[jotaen]

I’d be curious to learn about use-cases regarding this, so I’d appreciate if someone would share how they’d intend to make use of it.

[jotaen]

I see this topic as a longer-term discussion, since e.g. allowing [x]it! to appear in markdown (or even making [x]it! itself a superset of markdown) is a bit of a paradigm shift from the current concept. Currently, [x]it! is designed as a data language, which has a relatively pleasant and “humane” textual representation, while still mapping to rigorous data structures. → A file is basically a collection of item groups; item groups can have titles and items; items can have status, priority, due date and description.

I think it’s always a balancing act between two poles: a free document structure allows for more flexibility. It can account for different use-cases, and users typically have to bend their minds less, because they don’t have to think as much about syntactical rules and how they “are allowed” to express their thoughts. On the other hand, strict and constrained document structures make it easier for tools to work with the language. That, in turn, the user might benefit from via more powerful tooling support, especially when it comes to tools beyond the text editor. As a by-effect, a strict structure might also encourage users to express themselves more clearly. (Which can be boon and bane at the same time, of course.)

I can contribute one data point from my other plain-text project klog (a file format for time tracking). We basically had the exact same discussion there. The document structure of a klog-file is similarly stringent as [x]it! is right now: a file is a collection of records (a container structure at a certain calendar date), and a record contains time entries that each add or subtract from the total time. There is otherwise no free text allowed within the document, and the summaries/descriptions don’t support any markdown-like formatting. While it sometimes might feel limiting that no other text can be added around the data for further context, the file structure is dead-simple, very intuitive for humans to understand, and straightforward to work with programmatically. In essence, you could say that a klog-file is a human-readable database. That idea is what I am currently after with [x]it!

Of course, this is also largely a matter of personal preference. One reason why something like Emacs Org Mode, or other “combined” approaches are not appealing to me is that I find their openness to be too complex in the end. For me personally, simple, focussed and dedicated formats work better, even if this approach might require me to maintain multiple files in different formats. I recognise, however, that it doesn’t work that way for other people, and that there are different or even contrary preferences in that regard.

One note about markdown specifically: I would be unsure whether the current [x]it! syntax would be the best way to go then. Markdown already has lists, so the rules for aspects like multiline items or nesting are already there. So it might be better to leverage that ability and build on top of it, i.e. to extend markdown instead of embedding a new and independent concept.

- [ ] !!! Do this
  - [ ] ! Sub task 1
  - [ ] Sub task 2 -> 2022-04-16

---

tldr: For the near-term, I think it’s worth to consider the text below the headline, for being able to provide some additional context about a group of items. I think that would be a useful and relatively straightforward addition, and I wouldn’t expect it to complicate the language rules significantly. That being said, I’m not categorically against opening the spec up to support features like text formatting or free text. But it’s not what the current concept of [x]it! is about, so I’m not sure whether it will realistically end up there.

[ryanolsonx]

For the near-term, I think it’s worth to consider the text below the headline, for being able to provide some additional context about a group of items. I think that would be a useful and relatively straightforward addition, and I wouldn’t expect it to complicate the language rules significantly

I like that. I think adding information after a group can be extremely helpful. Again, like you said, we need to find balance.

[walterl]

"... i.e. to extend markdown instead of embedding a new and independent concept"

This is The Way.

xit looks like a great format for tasks. I particularly like the focus on simplicity, human readability, while remaining machine parsable. It also has all the most important task management features that most other formats (including Markdown) lacks.

That said, I can't see it gaining very wide adoption while it remains essentially unintegratable into existing formats. @jotaen You correctly identified the trade-offs involved when it comes to strictness of file structure. So the question must be asked: who is the target audience for xit? Is it humans, or computers?

Currently it feels like xit is stuck in the middle between those two. On the one hand it's an entirely separate file format that small scale/individual users would need to adopt, commit to, and find ways to integrate with the rest of their data. While the format is simple, it would increase overall cognitive load in a wider context. On the other hand larger scale use cases would probably benefit more from a more machine friendly (structured) format, like JSON or a database.

So if, as I suspect, the target audience is human end users who prefer text based formats, xit could provide considerable more advantage, and gain considerable usage, if it were to rather extend Markdown.

Extending Markdown, xit's benefits would remain, since very few changes would have to be made. The biggest change I can identify is subtractive (arguably simplifying the standard further): removing title support in favour of Markdown headings. Importantly, it would still be as machine friendly as before, since xit parsing is simply limited to lists in Markdown documents. I.e. xit tooling can reuse existing Markdown parsers.

The broader benefits would be huge, though. The most important of which, as mentioned, is integration into existing systems and documents. Even systems without tool support for xit would be able to leverage xit, since it's still "just [Markdown+xit] text". This means users can progressively opt in to xit features and tooling, without having to commit to it fully.

Extending Markdown will also automatically "import" all of the useful Markdown features, such as sub-tasks (as shown in your example, and an indispensible feature to me), text styling, and links (another indispensible feature to me).

I would be interested to learn about use cases that would benefit more from the current xit as a completely separate file format.

Personally I'd love to start using xit, but would find it more troublesome to mix-and-match with my existing Markdown notes and task lists.

[jotaen]

Thanks for taking the time to write up your thoughts!

who is the target audience for xit? Is it humans, or computers? Currently it feels like xit is stuck in the middle between those two.

I think your analysis is on point, and I can see where you are coming from. I think there are different premises, though: for example, I wouldn’t describe [x]it! as being “stuck” between humans and computers, but that intersection was actually exactly what I was aiming for. I’ve already tried to describe the merits of this approach above, in my comment about the time-tracking format “klog”.

What makes this design philosophy appealing for me is that I value its clarity and simplicity on the one hand, but I also think that it makes it really easy to create tools around it. I think, the more complex and “free” a file format becomes, the harder this gets: the overall syntax is more complex, other functionality can co-exist in the same file, and the data is embedded into a free-form context that’s hard to process automatically. Emacs Org-Mode is a good example for me here: while it’s certainly super powerful and feature-rich, I’m personally having a really hard time to wrap my head around all its capabilities. As far as I know, it’s still difficult to use Org-Mode outside of Emacs, which means that you are effectively stuck with that editor. (Which is not supposed to be a subtle attempt to bash Emacs.) When looking at the Org-Mode spec draft, I’m also not sure how easy it is to truly untangle and liberate the data format from Emacs as tool. At least, the entry hurdle for tool creators is pretty high.

In the end, I think there unfortunately is no jack-of-all-trades approach that happens to work for everyone. So for my brain an approach like klog (as mentioned above) or [x]it! works perfectly, because it’s straightforward and focussed on one single purpose. The barrier for tool creators is low, which increases the chances of being able to interchange tools without having to change data or workflows. I personally also don’t mind having a folder with a .klg file (for time tracking), an .xit file for tasks and todos, and an .md for notes, all next to each other. However: I can also see how others prefer a more “integrated” approach like Emacs Org-Mode, or something that extends or incorporates all that within Markdown, or some other document format.

I can't see it gaining very wide adoption while it remains essentially unintegratable into existing formats.

It really makes me happy to see other people using [x]it!, and that it apparently inspires some to build their own tools or editor plugins. I also think that sharing and being open to debate and discussion is an important contributing factor for improving and maturing such a project. However, I’m already happy enough if there are a handful people that enjoy using it the same way that I do. At the current point, I’m frankly speaking unlikely to change the basic concept of [x]it!, mostly because it works really well for myself. (That said, I’m still open to adjustments or improvements.)

Since the [x]it! specification is open-source, I’d be curious to see how its ideas might be adopted to cater other preferences or workflows. If someone would be willing to invest the time to integrate [x]it! into Markdown or some other document format, please do share it, I’d be genuinely interested to learn more about it.

Regarding the “integrability”: this reminded me of an idea that came up elsewhere in this thread, how xit syntax could be used within Markdown documents. I had originally forgotten about this idea, but now I’ve created a ticket in the [x]it! Sublime package, so it isn’t lost. Of course, this approach wouldn’t be a first-class integration, but at least it might be a viable workaround for someone.

[jotaen]

I think it’s worth to consider the text below the headline, for being able to provide some additional context about a group of items.

Regarding that idea, I’ve created a separate ticket for it here.

[jotaen]

For anyone who wants to use [x]it! in markdown, another approach would be to make use of embedded code blocks. The below screenshot demonstrates how that would look in Sublime Text.

This is just a super quick-and-dirty demo, for getting the idea across. The solution would differ for every editor, and in Sublime for example it would require a separate syntax definition that extends the markdown one. So there is some boilerplate involved, but it’s probably the cleanest “separation of concerns”.

For the Sublime Text plugin, see this issue.

[janzheng]

Hi everyone,

I've been using [x]it! for a while in Apple Notes, but today really wanted syntax highlighting in VS Code for files that have a combination of [x]it! and markdown.

I poked around (with Claude's help) and built this VS Code extension: https://github.com/janzheng/markdownxit

Feel free to change it around and use it; I probably won't put it up on Marketplace though, but anyone can take it / use it / put it on Marketplace ;)

[janzheng]

Oh and this also supports Github-style lists like - [x], though Github doesn't support "@/~/?" syntax so it ends up looking weird on their interface. Their loss lol.