Support multiple lines for entry summaries

[jotaen]

In record summaries (the text directly underneath the date) you can write multiple lines, but in entry summaries (the text behind the time values) you are restricted to a single line.

klog should support multiple lines for the entry summaries as well, by making use of the indentation. That allows for more flexibility.

As an example:

2020-02-02
    4h Today I finally answered all my
       unread emails, yay
    1h Reading

This requires a change of the spec, though, so I want to wait until v1.0 of the file format is finalised.

This issue came out of #50

[vladdeSV]

How would alignment of text be handled? Eg. must any additional lines start at the same column as the first summary line?

The tab character is allowed as indentation, which does not go well with aligning text.

2021-04-01
    1h foo
      is this allowed?
  is this allowed?

2021-04-02
  1h foo
	is this allowed (tab)
		is this allowed (tab x2)

2021-04-02
    1h foo
       bar
    07:00 - 17:00 baz
       is this alignment allowed?

[jotaen]

Good points, thanks for sharing. I haven’t thought it through entirely, but I’d intuitively say to keep the rules simple:

• First indentation level was, is and will be reserved for entries (just like now)
• If a subsequent line is indented twice (or more), it’s treated as the “overflow” of the summary text of the preceding line.
• There is one edge case in case someone indents with 2 spaces, because then it’s ambiguous whether the next line has increased indentation or whether you just switched the indentation style in between. (Which would be rather weird, but possible.) Not sure yet how to handle that best. For all other cases it should be clear. In theory you could also mix it, e.g. indent with a tab and then continue with spaces.
• If you want to do fancy alignment then that’s okay, but you don’t have to.

So I’d say all of this is okay:

2020-02-02
    1h With
       alignment

2020-02-02
    5:00-8:00 Without
        alignment

2020-02-02
    5:00-8:00 With
              alignment
    1h        With overall
              alignment

2020-02-02
    19:00 - 23:00
        Move entire text to next line

None of this is okay:

2020-02-02
    No entry value

2020-02-02
    1h Next line is
    not indented at all

2020-02-02
    1h Next line is
     not indented enough

[vladdeSV]

Great examples!

Should this also be okay, in your opinion?

2021-04-01
    1h foo
                                                                  bar

[jotaen]

I’d say so, yes. It’s also fine (right now) to do this:

2020-01-01
    1h                                              foo.

[vladdeSV]

What would the JSON output look like? Specifically, will leading and trailing whitespace be included per line?

[jotaen]

Very good question. And I think it would be good to write that down in the specification even.

My intuition would be to disregard leading whitespace, but I haven’t really thought about it yet.
Trailing whitespace should always be preserved.

[jotaen]

I have thought about this some more, and to me it would be most simple to preserve leading whitespace and treat it as part of the copy. So basically, everything after the indentation whitespace is owned by the user. Considering this example again:

2021-04-01
    1h foo
                                                                  bar

The entry summary would be:

foo\n                                                          bar

That’s because indentation style is 4 spaces, so 2*4=8 spaces are removed from the second line.

If we’d just cut off all leading whitespace, then the following use-case could become a problem:

2021-04-01
    4h - Chores
         - Washed the dishes
         - Painted the walls

[jotaen]

In regards to the JSON output, it would be possible to change the structure from this:

... "summary": "foo\n   bar", ...

to this:

... "summary": ["foo", "   bar"] ...

Not sure that would be useful, I don’t have strong opinions here.

[jotaen]

What I’m still undecided on is how to define the second indentation level exactly. Most simple would be to say that the second level is twice the first, e.g. 2 spaces → 4 spaces, 3 spaces → 6 spaces. That makes the following use-case inconvenient, though:

2020-01-01
    2h Some text that
       continues on the next line.

When using 4 spaces as indentation, the second level must start at column 8. In the example above, the user might want to start at column 7, though, to align with the previous line.

So for flexibility, the second indentation level could just be defined like “one indentation plus one tab or 2 (3?) spaces”. Which would imply that the indentation style must only be consistent throughout the first indentation level. Just 1 additional space would feel weird to me, so I think it should be at least 2, maybe even 3 (since the narrowest entry is 2 characters plus one space, e.g. 4h ).

[abrahambahez]

This would be a great feature!

I was using klog since last year, but really struggled with the habit of capture tasks and events a posteriori, so I abandoned it. Then I read this two strategies by Scott Nesbitt and Jeff Huang and immediatly return to klog with a little repourpose. So my actual workflow is a both prospective and retrospective time based version of those techniques. I'm sharing it here hoping that my use case makes sense (if this comment is considered out of place I can move it to another issue).

I do a tasks and events review every morning by creating a record and a summary with one line per item:

2022-01-24
Do A
Meeting with #JohnDoe
Review X

Then I try to timeblock each item and correct/adapt as the day goes:

2022-01-24
    9:00 - 10:00 Do A
    10:00 - 11:00 Meeting with #JohnDoe | this is something I'd like to remember later
    11:30 - 12:00 Review X

If I have an idea or a comment, I simply append the text separated by a pipe, BUT it could get really messy, so multiple line summaries in entries would make the file format so much readable. By the end of the day I do a little refactor of the record, adjust some times and run the report by tag. This is my reflection stage. Since this is a plain text format I can filter ideas, comments and stuff from the file as necessary.

I know that klog's goal is not time blocking but I honestly see this potential in the format and it really helped me to keep recording my activities consistently. Even I'm considering to connect this file to the Google Calendar API to share my schedule with my team.

Thanks for the tool mate!

[jotaen]

Cool workflow, thanks for sharing! I’m also regularly running into cases where I miss the ability to break entry summaries.

I’ve been doing some refactorings in the klog parser last year already, to prepare for multiline entry summaries. I’m hoping to wrap it up soon and include that functionality in the next release after v3.3. (Likely within the next two months.)