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.

[jotaen]

I also restored the original title and opened a separate issue for the multiline entry summaries, because I think your initial request was mostly about markdown and the multiline thing somehow came out of it.

[tecunningham]

Thanks Jan for the really thoughtful reply.

I've been using klog for a little over a month now, and it's been great. My workflow is just to keep my KLOG file open in vs-code and edit it directly, very occasionally I run the commandline program to get summary stats, or I generate a visualization in R.

When I'm working I usually keep a markdown log of meetings, each with a date-stamp, and I'm starting to think it would make sense to combine the two things (time-tracking and meeting-records). So I think I'll do a little experimentation/thinking to see whether it makes sense for me to combine them. (Vladimir below says that these types of systems often become too ambitious & complex, & that seems a reasonable fear, but I'll do some testing for myself).

Your examples of ambiguous entries in markdown are good, though I'm not sure it's very different from possible ambiguities in the KLOG format, or ambiguities in the MD format, and a syntax highlighter could help prevent you from making mistakes.

[tecunningham]

BTW I found one other project which is roughly what I had in mind, though it appears it's not maintained:  https://github.com/zevaverbach/markdown_timesheet

[jotaen]

There is also mdtimesheet, but I think it’s quite specific to that “plan” workflow. I haven’t tried it, though.

You are right about the ambiguities, klog also has them. What I probably tried to say is that I fear that a markdown-based format might be more prone to ambiguities than a specialised format. On the other hand, the latter has other disadvantages, for example that you cannot format the summary texts right now, so you are more limited in that respect.

In any event, thanks for sharing your thoughts and ideas, and I’m happy to hear that you enjoy klog. Curious to hear should you find or come up with something markdown-based, and also keen to see more of the R stuff.

[vladdeSV]

I personally value the simplicity of klog. I strongly believe the simplicity is its strength.

My own attempts to track time eventually spiral down into complex systems, which become unmaintainable after a while.

[chairmank]

I love using klog! I use klog as a ledger for invoicing hourly work. I would like to use it to send hypertext invoices with links to the work that I did.

I am interested in this suggestion to integrate klog with markdown. I think that it would be very powerful for the file format to specify simple, concise, unambiguous syntax for hyperlinks and inline code blocks. A markdown document can be embedded in a .klg file as a URL or as a comment with a header content-type: text/markdown. Maybe we can extends tags to implement these features in a backwards-compatible way.

[jotaen]

I see how more powerful text-formatting features could be quite useful, and allow for more advanced use-cases. I have to frankly say, though, that I’m reluctant to add them to the spec. Formal markdown specifications such as CommonMark are super comprehensive, and I’m worried that integrating them with or into the klog specification might turn into a rabbit hole. I see a lot of value in the simplicity of the current klog specification, both from an “end user” perspective, but also (or: especially) from a tool creator point of view. The more sophisticated the spec is, the higher the entry barrier will be for people who want to create syntax highlighters, CLI tools, or other kinds of programs. For example, I find both the current CLI tool and the Sublime Text plugin quite well to maintain, which I believe is largely due to the focus and specificity of the file format.

That being said, if someone wanted to play around with an idea like “klog-flavoured markdown” or “markdown-flavoured klog”, I’d still be curious to explore and learn about it.

Another option, albeit slightly less powerful and less elegant, would be to embed klog fragments as code blocks into markdown, like

# Some Document

*This* is markdown, with [links](http://example.org) and all that.

```klg
2020-01-01
    8:00-15:00 Work
    -45m Break
```

More notes, etc.

This would enable editors and tools to recognise and process these klg snippets, e.g. for syntax highlighting: