Support comments in the file format

[thiloplanz]

It would be useful if the file formats supported (block or line) comments.

These would be ignored completely by the tool.

[jotaen]

Could you give an example how you would make use of comments if they existed?

[thiloplanz]

The CLI filters always do an intersection

You are right, I missed that somehow.
I'll try using that for the #sprint7 use-case, that should cover it very nicely. And this is superior to using comments here, because the reporting syntax already understands "day-level tags", removing the need for an external tool to process the comments.

[thiloplanz]

Two more use-cases for comments:

• templates to copy frequently used records from
• point-in-time entries Point-in-time entries #46

[jotaen]

@thiloplanz since you mentioned templates: there is a hidden, experimental implementation for using templates as part of the klog create command. See here for usage: #12

I’m still undecided on this feature, that’s why it’s not “advertised” yet.

(Update from 2024-05-04: experimental template support was abandoned.)

[maxiride]

The CLI filters always do an intersection (i.e. they are combined with an AND so to speak).

@jotaen
is there a way to query the opposite of your example?
For instance all the #sprint7 records without #qa

Expected output:

2020-01-01
#sprint7
    1h #cs
    1h #dev

[jotaen]

No (copying over my answer #65 for reference), currently the filters are quite simple, so you can’t do things along the lines of OR or NOT. I am open to making the filters more powerful, but so far I couldn’t think of an easy and “CLI-native” way to do that, and I don’t want to build a query language 😁

[StefanSchroeder]

There hasn't been any activity on this suggestion for some time. I am also interested in the ability to have comments.
Since '#' is already used, comments could start with '//' or '--'...

[jotaen]

Thanks for sharing your thoughts on this. I’d be curious, which use-case would you have in mind for comments?

I personally came to think that comments (like in the programming-sense) wouldn’t really be a good fit for the klog file format. klog already supports capturing text through summaries. I’d be concerned that adding another way of specifying text might potentially cause confusion. The other issue is that comments would increase the complexity on the tooling side of things.

[StefanSchroeder]

I disagree that tooling would be affected significantly. The Reader of the file would have to add a single line of code to discard any line starting with the comment tag. I guess the only confusion could arise if the user chose to start a 'story' unknowingly with a comment sign which then would disappear in any display of the story. With '//' as a comment tag this risk is negligible IMO. Apart from that I agree with the assessment by @alerque below. I think it's more likely than not that one day everybody will think "if I only could add comments natively, I wouldn't have to use some awk/sed magic to preprocess my klog files". ;-)

[alerque]

Comments are a staple tool and no plain text format without them is as useful as one with. I use them extensively in my plain text accounting files (hledger). The uses can be notes to self about things to fix or update (almost all text editors have facilities for handling TODO: inside file format comments no matter what the file format is), or things that don't fit in the actual meta data properly, half-finished entries that shouldn't be active yet, temporarily hiding content from the CLI tooling, adding meta information for use outside the main tooling. An example of this last use would be hledger edit, a tool that queries a any number of related ledger files for some query pattern using standard hledger queries, then combines them into a temporary ledger file that can be edited with just the matching transactions, then when you close the file it can sort out where all the pieces came from and update the original ledger files with the edited transactions all in the original order. All that while still allowing the temporary results ledger to itself be a valid ledger. This is the kind of 3rd party tooling that can be enabled by having comment syntax available.

[lachholden]

I would probably use comments to mark out week-by-week or month-by-month headings for editor folding, similarly to how I do in beancount. That's a situation where I similarly have a single plain-text document that grows with time as more data is recorded.

Could also be useful for planning out a day at the start - under a record's heading have comments with approx. times for different tasks, and delete them as they get replaced with the real recorded values. In this case, maybe it could be useful to have a flag on klog print to either include or strip comments (I guess a comment is associated with a record if there are no line breaks between it?)