Spec as subset of markdown

[tecunningham]

This is a very extreme suggestion, but I thought it's worth mentioning to see what other people think.

I've been putting longer descriptions alongside each of my entries, and it occurred to me it'd be nice to be able to integrate the whole thing with markdown, such that the klog format is a subset of markdown.

Here's one way it could work: an entry is a bulleted list with a time-code, and the entry-description is anything which is attached to that bullet (including sub-bullets, etc.)

# 2021-03-22 Monday
- 07:00-08:30 #writing, wrote to Arash, Jon, Per.
- 08:30-10:30 
   - Found Hall's marriage theorem, which says saxophone and diagonal representation of inequalities are equivalent, which allowed me to prove the diagonal lemma & so the theorem.
   - Was able to cut out a bunch of extra material from the paper.
      - Including cutting all the corollaries.

- 13:00-18:00 Read
   > "It is in the chemistry of these subtle substances, these curious precipitates and explosive gases which are suddenly formed by the contact of mind with mind, that James is unequalled"

# 2021-03-23 Tuesday
Terrible hangover.

- 14:00 coffee
- 14:00-13:00 read my letters, wrote to my mother.

[jotaen]

I have been thinking about that as well already and also find myself using bullet points in the summaries. (Not indented, though.) I agree the summaries could allow for more flexibility, so it’s good that you bring this up so that it can be discussed further.

A few general upfront thoughts: I think there is a natural overlap between the three concerns of time tracking, todo’s and note keeping. It’s a tricky balancing act to decide where to draw the line, and I’d like to keep klog focussed on time tracking primarily. What I like about the current summary style is that it feels “cheap” (read: simple to memorize and understand) with a quite straightforward (read: basically non-existent) syntax. I also don’t want to force users into a certain usage scheme but rather allow them to make up their own according to individual needs. There might be people who don’t use summaries at all, but who only want to enter the “naked” time data.

However, on the other hand, users shouldn’t feel unnecessarily limited by the summaries, and there are indeed a few shortcomings at the moment. I feel that making klog a subset of markdown probably goes a bit too far, but it should be possible to use something like markdown/todo.txt inside the summaries more easily.

Two things have been floating around in my head:

Multiline entry summaries

As you pointed out, the entry summaries (the text directly behind the time values) can only be one-liners. It could be possible, though, to have multi-line text as well, which could be achieved by expanding on the python-style indentation like so:

2020-01-01
    4h Was able to cut out a bunch of extra material from the paper
       including cutting all the corollaries
    1h
        - this
        - that

So you would basically be able to continue the text on the next line, with increased indentation level.

Allow indentation in record summaries

Currently there can’t be indentation in the record summaries (the one underneath the date), because indentation is reserved for the entries. There could be some sort of marker though, similar to blockquote syntax in markdown:

2020-01-01
| - Did this and that
|    - Includes this other thing
|    - And this one
    8:00 - ? Just started

You could do this right now already, but of course the | (or whatever character is used) would be part of the copy then. But the spec could reserve a special marker that gets stripped away by the parser. I’d find it important for this to be optional, in order to not loose the simplicity for use-cases where this kind of flexibility is not needed.

[jotaen]

I’ve been thinking about this some more and I think the multiline entry summaries would be a cool feature to add. The concept is fairly straightforward and I also have noticed to feel limited by being restricted to only one line.

This would require a change of the spec, though, and I’d like to finalize the v1.0 version of the file format before adding anything new.

I moved the “indentation” topic to a discussion, because I’m more tentative about it at the moment. We can keep this issue here focussed on the multiline entry summary then.

[tecunningham]

Happy to hear that -- and happy to give thoughts on any ideas you might have.

You mentioned in a previous post "I feel that making klog a subset of markdown probably goes a bit too far." Could you expand a bit on what the drawbacks of that would be?

There would be many advantages (I think): you could use existing markdown highlighting, processors, & you'd naturally have all the features of markdown.

It certainly would break backwards-compatibility, and it would probably be require reasonable amount of work to implement, but are there drawbacks specific to the format?

[jotaen]

I think building on top of markdown would change the notion of klog. Currently, klog is basically a data format that happens to be human-readable. If it was markdown, I think it would feel more like a journal that allows for time tracking additionally. That’s also what I meant earlier: I think there is a natural overlap between time tracking and journaling, but it’s a philosophical question where to put the focus on.

From a technical point of view it might be tricky to define the file format so that it isn’t ambiguous or hard to memorize, because with markdown you generally have the full freedom to structure the document as you please. So a klog-flavoured markdown would either a) have to be very restrictive and narrow down what is allowed and how it’s supposed to be structured. In this case I think you’d lose a lot of the benefits of using markdown, however. Or b) the rules would be broad and permissive, but that might lead to complications or ambiguities. There could be text in between sections, or other headlines, links, footnotes, etc. Consider the following example: which of the data would be understood? And would the rest be silently skipped, or would klog raise errors or warnings? (Because it might have been done on purpose, but it also could have been by accident).

# 2021-03-22 Monday
- 07:00-08:30 #writing, wrote to Arash, Jon, Per.
- [1h Tennis](https://my-tennis-club.com)

# Tuesday, 2021-03-23
1h Workout
8:00 - 9:00 Tennis again

## 2021-03-24 (Wednesday)
- I did the following things:
  - 09:00-10:00 Breakfast
  - 1h Workout

I found your initial example quite interesting, because I use klog completely differently. My summaries (if I write them at all) are rarely longer than 5 words, and I treat them more like a reminder than like a journal with detailed descriptions. So I perceive summaries basically as short annotations of the data for future reference. If I want to take more extensive notes about something, I usually do that separately. It’s interesting anyway to see how the habits and preferences are different.