Adding tag support to timeclock format

nobodyinperson commented 4 years ago

Hi,

Thank you very much for hledger, it's awesome. I just began using the timeclock format for time tracking. A perfect match with hledger, indeed.

I noticed that it is not directly possible to use tags with the timeclock format. Interestingly, there also seem to be no issues about this topic at all.

Demonstration

Consider the sample.timeclock file from hledger.org, with some tag comments added to the end of each comment:

i 2009/03/27 09:00:00 projects:a  ; successful: yes
o 2009/03/27 17:00:34
i 2009/03/31 22:21:45 personal:reading:online
o 2009/04/01 02:00:34
i 2009/04/02 09:00:00 projects:b  ; successful: no
o 2009/04/02 17:00:34

Now, hledger doesn't ignore these comments:

hledger -f sample.timeclock print
2009-03-27 * ; successful: yes
    (projects:a)           8.01h

2009-03-31 * 22:21-23:59
    (personal:reading:online)           1.64h

2009-04-01 * 00:00-02:00
    (personal:reading:online)           2.01h

2009-04-02 * ; successful: no
    (projects:b)           8.01h

However, hledger also doesn't seem to care about them, as it is not possible to filter by tags now:

hledger -f sample.timeclock bal tag:successful=yes
--------------------
                   0

There exists a workaround by simply parsing the print output again with hledger:

hledger -f sample.timeclock print | hledger -f- bal tag:successful=yes
               8.01h  projects:a
--------------------
               8.01h

Proposal

Handling tags in timeclock format exactly like in the journal format.

Environment

up-to-date Manjaro XFCE4
hledger 1.17.1.1 from the official repositories

nobodyinperson commented 4 years ago

This would also be a possible solution for #850.

simonmichael commented 4 years ago

You're right, this isn't implemented yet. In fact semicolon comments aren't a feature of the timeclock format - none of the timeclock implementations (timeclock.el, ledger, hledger) mention them, ledger and hledger just treat them as part of the description. So eg this will work:

hledger print desc:'successful: yes'

Do you think it's worthwhile extending the timeclock format as implemented by hledger to allow comments (and tags) ?

nobodyinperson commented 4 years ago

Absolutely! Tags are so incredibly useful and make hledger extremely versatile. Wild assumption: everyone using hledger utilizes tags at some point and is familiar with it. Tags are one of the reasons hledger is so much better in structuring transactions and avoiding duplicate account structures than alternatives like GnuCash for example. It feels right to have this functionality also available in the timeclock format. Just a couple of examples for tag usage in timeclock format that come to my mind immediately:

tracking the location of a time period (if the „account” is used for something more abstract like work/hobby/etc...), e.g. to distinguish home office from regular presence work or during business trips.
avoiding duplicate substructures in the „account” when having multiple jobs by outsourcing specifics to tags
marking time spans as billed/paid as needed in #850
adding descriptive metadata to time spans, e.g. whether a period of work was particularly challenging / might get extra bonus / etc...

The only problem I see is when someone already used the semicolon in their description for other purposes (e.g. enumerations) which would break their system or even cause hledger to fail parsing the characters after the semicolon as comment (can hledger actually fail during comment parsing?). A solution for this problem would be to make tags for timeclock format an opt-in feature for backward compatibility, e.g. by introducing a command-line flag (yet another option, meh...) or via an environment variable (e.g. HLEDGER_TIMECLOCK_ENABLE_TAGS=1) which people could include in their shell configuration. Although, when considering making tag support for timeclock format an opt-in feature, one might as well just keep it the way it is and let people re-parse the output again as I demonstrated above. I just wonder how long of a timeclock file it will take to let re-parsing add a significant processing time overhead to make it annoying to use.

simonmichael commented 4 years ago

Thanks for the examples. There's a downside to deviating from/complicating a "standard" format and making it our own. It might be ok in this case because:

there aren't a lot of tools using this format
current Ledger and older hledger would still read the new format, though not recognising the tags as tags (and not displaying parts of descriptions following a ; in print and register reports)

Breaking compatibility is also bad, but:

hledger users are used to ; beginning a comment, so they don't use them in journal descriptions, and maybe out of habit they avoid them in timeclock descriptions too ?
hledger and Ledger timeclock files containing ; would still be readable. (But anything after ; would no longer appear in hledger's register report.)

We could argue that this is not really needed because you can achieve much of the same functionality by writing adhoc tags in the description.

Or that it is needed, because some hledger users will find it surprising that ; in a timeclock description does not start a comment, especially when it seems to be displayed as one by print. The fact that it's being parsed as part of the description is not clear, and different from the rest of hledger.

Timedot format has its own behaviour: things after ; are ignored, and not printed as a comment, or parsed for tags.

All considered I'm inclined to agree that semicolon in timeclock files, and in timedot files, should create comments, with all the usual characteristics: their content can't be searched, except for tags which can be, and they should be displayed by print.

We could poll the mail list as well.

nobodyinperson commented 4 years ago

Thanks for putting this on the mailing list.

We could argue that this is not really needed because you can achieve much of the same functionality by writing adhoc tags in the description.

Although - being just substrings in the description - you couldn't --pivot over these ad-hoc tags, which in my opinion is crucial.

lestephane commented 3 years ago

How about supporting a file extension called .timeclock2, the same way you have .json5 to support comments in json files? Just thinking out loud. Then everyone is happy.

simonmichael commented 3 years ago

If someone wants to implement proper comments and tags in hledger's timeclock format, I'm fine with that - for the reasons mentioned above, I think it'd be a low-cost enhancement and there's no need for a new format.

linuxcaffe commented 3 years ago

Huge +1 for comments and tags in timedot and timeclock!

linuxcaffe commented 3 years ago

I'd like to caveat on that Huge +1, in light of my recent timedot enhancements #1754 (since closed, preferring solution below) Comments and tags for timeclock, just like regular journal entries, for sure! (I'm already using them, just can't query based on them) But for timedot, you can comment all over the place, and imho what's needed is the payee/description field. Because each timedot entry is on a single line, any associated metadata has to be on that line. I would rather have description and no comment+tag, than vice-versa, what I really want is everything! How about this;

<acct:sub:sub><2+ spaces><qtty><2+ spaces><description text><2+ spaces><;><comment and :tags:>

sleep                7
job:store            8.5         cleaned, set up xmas decorations
job:mary:reno        ...         bathroom drain repair                ;sink grill didn't fit :plumbing:
ent:reading          .... .      Kurt Vonnegut - Cat's Cradle         ;insane! loved it! :fiction:funny:
phys:workout         25min       ;reps: 305

all fields separated by two-or-more-spaces, which (as I learned on hledger,org) using wide, expanded tabstops, tends to nicely tabulate the entries! The metadata would be optional, of course, and if the comment/tag field was always preceded by <2+ spaces><semi-colon>, then one could skip the description and go straight to the comment/tags.. i donno why, but you could ;-)

simonmichael commented 3 years ago

I reopened #1754 for the timedot discussion, so we can avoid getting mixed up.

simonmichael commented 1 year ago

Resolved by #2031.

nobodyinperson commented 1 year ago

Thanks, Michael 😃

simonmichael / hledger