Specification clarifications

[vladdeSV]

I have been reading through the specification, and I believe there are a few things which needs further clarifications.

I. Records

Summary

It MUST be separated from the entry one “space”

Incorrect wording, I believe.

Range

There MUST be a - between the two values, which MAY be surrounded by one “space” on each side.

Ambigious. Can there be ...

• ... multiple spaces?
• ... spaces on just one side?

klog currently actually accepts ranges in the format of 00:00 -01:11

The ? MAY be written in repeatedly, e.g. ???.

Incorrect wording. Maybe use "in a recurring succession"?

Duration

I would very much like to see a clarification that the minute part cannot be greater than 59, if it is in combination with an hour part. I assume this is the intended behaviour, since klog throws an error if the minutes are greater than 60. However, surprisingly it actually accepts 1h60m and interprets that as 2h. I believe this is a bug with the program, but I might be wrong.

II. Organizing records in files

Subsequent records MUST be separated by one “blank line”; there MAY be additional blank lines.

Contradictory. I interpret the first sentence as "must be separated by one and only one blank line". I wish for this to be clarified.

[vladdeSV]

As a side note: The specification has been a tremendous help when writing the VS Code syntax highlighting.

[jotaen]

🙇 I’ve already fixed the phrasing and the CLI error regarding 1h60m (which was a bug indeed); 91f30b6.

Range

My reasoning was this: I didn’t want to be too strict about whitespace unless that would lead to ambiguity. I think it’s important to support both 8:00 - 9:00 and 8:00-9:00 (the former is what the CLI currently outputs). It would feel overly pedantic to me to reject 8:00- 9:00 or 8:00 -9:00, even though this formatting should also not be encouraged. In the spirit of “be liberal in what you accept…” I’d like to see this indulgence baked into the spec, in order to force all implementations to be user-friendly in that regard. I guess it’s tricky though to put this sentiment into writing – what do you have in mind?

Duration

I like that suggestion, it makes a lot of sense. What do you think about:

The minute part MUST be an unsigned number which MUST be immediately followed by the character m. It MAY be 0m. When the hour part is present, the minute part MUST NOT be greater than 59m, e.g. 1h59m; otherwise it MAY be greater than 59m, e.g. 119m (it is RECOMMENDED to break this up, though). If the minute part is missing, a value of 0m is assumed.

I was also thinking about using the term integer instead of number? (In all occurrences in the spec)

Organizing records in files

This is similar to the whitespace in the range: there must be one blank line, but a document shouldn’t be rejected if there are more blank lines. (The recommendation is exactly one blank line, though.) Maybe better:

Subsequent records MUST be separated by “blank lines”. The number of “blank lines” SHOULD be one; there MAY be more than one.

[vladdeSV]

I’ve already fixed the phrasing and the CLI error

Awesome 🎉

I guess it’s tricky though to put this sentiment into writing – what do you have in mind?

Definitely tricky. My suggestion would be to something similar to: MAY be surrounded by "spaces". SHOULD have equal amount of "spaces" on either side. (Edit: Hm, "surrounded by" still makes it sound like if there are spaces they need to come in pairs.)

Possibly, you could fit in some recommendation to have not have more than one space on either side: SHOULD NOT be surrounded by more than 1 "space". Or maybe just leave it as it is, and make it an implicit recommendation with how klog prints a timespan.

I was also thinking about using the term integer instead of number?

Ah, I glossed over this. When I started writing the syntax highlighter I remember being confused to whether a number could contain decimals or not. I am unsure what the best approach would be, but some clarification what a number must only contain "digits".

Maybe better:

That is definitely better. My suggestion would be to specify the blank lines in singular, since I can interpret MUST be separated by “blank lines”. as is must be separated by multiple blank lines (opposite of before, haha).

My final suggestion would be something in the veins of Subsequent records MUST be separated by at least one “blank lines”. The number of “blank lines” SHOULD be one..

Please note that I think this also could be written better, but I just cannot find that "one-liner" which encapsulates it all.

[jotaen]

Range

Agree, the term surrounded can be misleading. Maybe

There MAY appear “spaces” on either side of the -; for this case it is RECOMMENDED to use exactly one “space” on both sides.

Number <> Integer

I think the best is to use “integer” and define that in the Appendix as a technical term as an unsigned number without fractional component.

Blank lines

Haha, oh god, this is brain-racking 😆 How about:

There MUST appear one “blank line” between subsequent records. Additional “blank lines” MAY appear.

It’s only a slight change in the phrasing. I would read the first statement like this now: there needs to be a blank line somewhere between records, but it doesn’t restrict what else there might appear additionally.

[vladdeSV]

I think all these would be great additions 👍

[jotaen]

(Not sure whether you were notified by Github: #11)

[jotaen]

Hang on, what happened with this bit? 🤣

The minute part MUST be an unsigned number which MUST be immediately followed by the character m. It MAY be 0m. When the hour part is present, the minute part MUST NOT be greater than 59m, e.g. 1h59m; otherwise it MAY be greater than 59m, e.g. 119m (it is RECOMMENDED to break this up, though). If the minute part is missing, a value of 0m is assumed.

You agreed with that, didn’t you? Then I’ll add it as well.

[vladdeSV]

I, uh, missed that 😅.

That is an addition I want to be added :)

[jotaen]

Added 2b8eca9