Syntax for continuing by timestamp

[Tim Weber]

I'm splitting #3 in three separate issues, this is one of them. Example file:

1234  implement CLI parser
1245  customer called, discussed some open questions
1320.  # bathroom break

Now it's 13:25 and I want to continue work on "implement CLI parser". My original suggestion from #3 was to use a syntax like 1325^1234, and I still think this is how it should be. There are just some details left to be decided.

One thing to keep in mind is that even though our examples all used HHMM timestamps, the format actually supports six-digit timestamps, i.e. with seconds, HHMMSS. Users are allowed to use both, in the same file, interchangeably. If no seconds are specified, they of course default to 00.

Originally, I suggested the following:

• ^1234 matches 1234, 123400 and even 123456
• ^123400 matches 1234, 123400, but not 123456
• ^123456 matches 123456, but not 1234 or 123400

In other words: A search expression (after the ^) that's a HHMMSS timestamp matches with to-the-second accuracy, while a search expression that's just a HHMM timestamp matches with to-the-minute accuracy. Some thoughts about this:

• If the user is writing the file completely manually, they will most likely use HHMM timestamps both for new entries and for continuations.
• If the user specifies HHMMSS timestamps, they are most likely using a tool or editor plugin that assists them. This tool can then also assist in referencing the correct six-digit timestamp in the continuation line, or, if they write the reference manually, they could of course reference the previous entry with to-the-minute precision only.
• In both cases, referencing the correct line doesn't seem too cumbersome to me.

@L3viathan brought up a shorthand form: ^34 would match 1234 or 0934, depending on which is closest. We've discussed it on Twitter: A simple substring match would be consistent and easy, but also confusing: What if your ^34 suddenly matched 1342? We decided that saving a few keystrokes is probably not worth it. (Also, what about ^15? Would that match only 1315 or also 1520? I think we shouldn't go there.)

So if nobody has any further suggestions or use cases, I'll probably leave it at my original suggestion outlined above.

One thing to note: This style of back-referencing doesn't let you look past the closest match. Check out the following example file:

2019-06-16:
124555  cook a delicious meal
130827.

2019-06-17:
123421  implement CLI parser
124555  customer called, discussed some open questions
132005  export time tracking to Jira
132038^^

At this point, I can't reference the 132005 entry by writing something like 151232^1320 alone, because the closest match back in time would be the 132038 entry. I'd have to write 151232^132005 to explicitly rule out the other entry. Also, I can't reference the 124555 entry from yesterday at all, because even with maximum precision, the closest match is today's customer call.

This is by design and fine as it is. Your files should stay readable and understandable from a human perspective. We're not designing a database with cross-references. Copy-pasting a line to the next day to continue working on that task is totally okay.

[Tim Weber]

I have put some more thoughts in these last two paragraphs. Maybe it would be nice to have a syntax that allows us to refer to an entry on a specific date. Picking up that last example again, something like 151232^2019-06-16 124555 would allow me to skip past the entry on the 17th and continue the one on the 16th.

This way, we could reference any previous entry in the file really, because date-/timestamps are supposed to be unique. Of course, referencing an entry from two months ago will make your file pretty much unreadable for a human, but I can imagine twisted perfectionists wanting such a thing in order to not have any redundancy in their file.

[Tim Weber]

Sigh. Two more things to consider came to my mind: previous days and timezones. Consider the file from the README (I've removed some irrelevant lines):

# I'm in Germany right now.
TZ Europe/Berlin

2019-06-03:
0905  think about concept #tstxt
0931  write readme #tstxt
1402.

2019-06-04:
1025  e-mail to customer #asd !$
TZ Europe/London # we've crossed the timezone border
0933  ASD-1701: improve design

First, timezones. Assume I'm at the end of that file and want to add a new entry at 11:15 that references the e-mail to customer entry by timestamp. How would I do that? There are three possible answers I see:

1. Using 1115^1025, i.e. by using the timestamp as it appears in the file, even though I'm now technically in the London timezone and in this one the entry started at 09:25.

• pro: Easy to handle for both humans and editor plugins.
• con: What if I had another entry that started at 10:25 London time? I'd completely lose all means to refer to one of those entries by timestamp.

2. Using 1115^0925, i.e. by using the real time the event took place in the timezone the referring line is in (London).

• pro: The referencing problem ("con" from above) goes away.
• con: Humans have to convert between timezones in their heads, editor plugins are likely totally lost.

3. Don't allow cross-TZ timestamp references. It's a real edge case anyway, and you can use one of the other back-reference mechanisms.

• pro: No confusion, no divergence between Python's understanding of the file and editor plugins.
• con: One probably nice feature less. People who regularly travel between timezones might be sad.

I'm leaning towards 3, simply because I'd be disappointed to design either of the "con"s of 1 or 2 into the specification.

Second, what I called "previous days": When you reference a timestamp like 1115^0925, I've always assumed that if there's no 0925 in the current day, we'll continue looking backwards through the file until we find that timestamp (no matter the date) or we reach the beginning of the file. Is that sensible?

• What if I made a typo and my entry is now referencing a line from 8 months ago?
• What if I'm editing the start time of the line I'm referring to and suddenly the back-referencing line no longer targets an entry on the same day, but 8 months ago?

To be honest, both issues apply to the substring matching as well. I think we should, in the good old Unix fashion, assume the user knows what they're doing and not limit the back-referencing time span. But I'm open to other opinions, of course.

[Jonathan Oberländer]

I think it's not worth the effort, but for completeness' sake my scrapped thoughts:

2a. Allow explicitly specifying a timezone by means of UTC offset. If I want to refer to London time, I just use 1025+1, which then means 0925 UTC.

• pro: Same as 2, plus humans have a slightly easier time (assuming they know their tz's UTC offsets)
• con: Might be a nightmare to implement, because we'd have to look up in tzdata because of DST and friends... And humans are still somewhat confused, probably.

[Tim Weber]

@L3viathan Interesting idea, but yeah, I think currently it's not worth the effort. I will try to keep in in mind when designing the spec though, so that we could implement it in the future.