Allow multiple *open ranges* as "follow-up range"

[vladdeSV]

Preface

I manually write down my time tracking. All my entries are tagged and rounded to the nearest half hour.

This is how I write down a typical day:

2025-01-23 (8h!)
  08:00 - 12:00 #foo=bar
    lorem ipsum dolor sit amet, consectetur adipiscing elit
    sed quis odio sagittis, sagittis libero eget, bibendum dolor
    donec nunc eros :)
  12:00 - 12:30 #baz lorem ipsum
  13:30 - 16:00 #foo=bar
  16:00 - 16:30 #baz lorem ipsum dolor sit amet
  16:30 - 17:00 #foo=bar

When I start a new task, I denote it as an open range:

  08:00 - ? #foo=bar

I ofter work on multiple tasks and have to jump between those. For every time I switch task, I need to replace the ? and write down the current time twice – once for closing the previous task, and once again for starting the new task.

Suggestion

What if the spec allowed for multiple open ranges, but only if all open ranges are preceded by another range (open or not), except for the first open range.

This means that the above example could be written as

2025-01-23 (8h!)
  08:00 - ? #foo=bar
    lorem ipsum dolor sit amet, consectetur adipiscing elit
    sed quis odio sagittis, sagittis libero eget, bibendum dolor
    donec nunc eros :)
  12:00 - 12:30 #baz lorem ipsum
  13:30 - ? #foo=bar
  16:00 - ? #baz lorem ipsum dolor sit amet
  16:30 - 17:00 #foo=bar

The main benefit of this is for me – I don't have to edit the previous line when I start switch tasks.

  13:30 - ? #foo=bar
  16:00 - ? (no need to edit previous line)

Of course, my lunch break is a little bit odd, since I need to explicitly end the current task and start my next task after lunch.

Considerations

This change would be backwards compatible, since

1. the spec doesn't allow for multiple open ranges (they can't exist in other's documents)
2. current users can continue using one single open range per day

In order for this to actually work, besides the first open range, you cannot have durations precede any of the multiple open ranges.

2025-01-01
example 1
  08:00 - ?
  30m
  10:00 - ?
  ^^^^^^^^^^
Open range not preceded by closed range

2025-01-02
example 2
  08:00 - ?
  10:00 - ?
  30m
  10:30 - ?
  ^^^^^^^^^^
Open range not preceded by closed range

These examples would be allowed:

2025-01-02
example 3
  08:00 - ?
  10:00 - 10:30
  30m
  10:30 - ?

2025-01-02
example 4
  08:00 - ?
  10:00 - 10:30
  10:30 - ?

Having the last open range left open would generate the same warning as having just single open range.

2025-01-03
  08:00 - ?
  10:00 - ?

[WARNING] 2025-01-03: Unclosed open range

Author's notes

I am not sure this is actually a good idea, or if it's the best direction for Klog.

The terminology I use, "preceded by" might be off, since as long as there is a single "closed range" anywhere before another open range it can be inferred what is meant.

But it does raise some ambiguity, specifically in example 3, where you could argue both for and against the duration that appears between the open ranges – should the last open range be allowed and interpreted as a continuation of second entry on that day?

The examples might not be perfect, as I just wrote down what I thought of in the moment. They should be some guide to what I am trying to achieve though.

This is however something that I deal with everyday. I wanted to write down my thoughts and not keeping it all to myself. This one approach I could think of that would flow well with my current workflow, and stay coherent with the current syntax of Klog.

Additionally, I did consider if "follow-up ranges" could be written with something like ? - 10:00, but that would still require me to edit the current entry before I can create another entry. That would defeat the whole point of this.

Again, not expecting this to be implemented, just wanted to get my thoughts out.

[jotaen]

Awesome, thanks for this comprehensive write-up! You are not alone with your use-case; relevant references (though primarily related to the CLI tool): #267, #268, #273.

I wrote up some thoughts, just as a contribution to further explore and discuss your ideas.

Syntactically speaking, I’m not sure the 15:00-? notation would make sense here, because the ? symbol is supposed to reflect that the end time is unknown. However, with consecutive open ranges, the end time isn’t unknown for all previous entries, but only really for the last one. So I’m wondering whether the ? notation would be clear enough.

I’m thinking that in a series of entries (or “follow-up” ranges, or back-to-back ranges, or whatever we want to call them), the end time is actually redundant. So another approach could be some sort of syntax where you only need to note down the start time in a series of entries, like:

2000-01-01
  13:00 Some thing
  14:00 Other thing
  15:30.

(Where the . notation on the last entry would basically conclude the preceding series of entries.)

Beyond the syntax aspect, one thing that would be important to consider is that such a notation would also imply conceptual changes:

• Right now, entries are self-contained, so you can fully understand an entry of 15:00-16:00 without looking at the surrounding context. With “follow-up” ranges, you’d have to take into account surrounding entries to be able to understand an entry.
• Right now, entries are unaware of the order. So reordering or even shuffling entries doesn’t have any effect on the evaluation. With “follow-up” ranges, the order of entries would be significant.

You pointed out the issue when a duration were to appear in the middle of such a series. I think this would be a symptom of the above implications, because the rules around entries would become more complex.

Generally speaking, I think that such a feature touches on fundamental philosophical questions of the file format, which is a balancing act between overall simplicity and usage convenience: the (current) simple approach is easier from a “mental” perspective, but it can be more laborious in some situations, whereas more powerful features provide more convenience, but can also increase the overall “mental burden” of keeping all rules in your head.

There might be a different angle to solve (or at least mitigate) this use-case, however, because such a problem could also be tackled through tooling – i.e. that an editor plugin provides similar functionality to what the klog switch CLI command does. Say, you have the following record in you file, and you want to add a new entry 11:00-? More work and also “close” the existing range at 11:00.

2000-01-01
  10:00-? Work

The editor could provide shortcuts or special functionality like the following:

• You manually add the 11:00-? More work entry and hit a certain key combination to have the editor plugin replace the previous ? by the current start time.
  • The editor could even recognise that you have multiple open ranges, so it could also prompt you about this.
• More fancy: if your cursor is in the lexical scope of the 10:00-? Work entry, and if you hit a special key combination like “Alt+Shift+Return”, it creates a new entry and automagically takes over the start time to substitute the ? of the previous line as soon as you finished typing the start time token (see this faked demo gif, just to get the idea across)

I’m wondering whether something like this could be a viable middle ground between keeping the file format simple, but still providing enough convenience to cater these day-to-day use-cases. The downside is, of course, that you’d have to use an editor plugin (or some other tool) to have access to those conveniences.