Re: Extending timeclock.el

[John Task]

Eli Zaretskii <eliz@gnu.org> writes:

> Why not simply add the code to timeclock.el itself?  You can for now
> fork it and develop it separately; later, we will merge the changes.

That works, too.  My thinking was that timeclock.el worked perfectly
fine until now, and timeclock-modern.el would be a simple extension in
order to support a different workflow.  However, it also makes room
for improvement in other areas of the package, so I'll look into that.

> By "timelog format" do you mean the format of the log file
> read/written by timeclock.el, or do you mean some other format, which
> Emacs currently doesn't use?

I mean the current format read and written by timeclock.el.

> The codes are documented in the doc string of timeclock-log-data
> (assuming it is up-to-date ;-).

Yes, that's how I realized they exist.  But as I'm not well
familiarized with the package, they are still pretty cryptic from my
POV.  For instance:

  b  Set the current time balance, or "time debt".  Useful when
     archiving old log data, when a debt must be carried forward.
     The COMMENT here is the number of seconds of debt.

I understand every word here, and yet I don't really get what time
balance is or when to use it.  Also, old log data can be archived?

Of course, in this particular situation, I think it's pretty clear a
line starting with a 'b' doesn't indicate a track, and that's
everything the parser need to know in order to work.  At least for
now.

> There's no "0" there that I could
> see, but there is "O" (upper-case letter O).

I hate my font so much :(

> As for the "clock-out" issue: like I said, time trackers used for
> tracking work activities do have both 'o' and 'O'.  The former means
> "end of workday", the latter means "this activity will never again
> appear, because its project is 'finished'".  The former can indeed be
> represented as the start of "untracked" activity, but the latter must
> be also explicitly supported, because a reasonably useful report or
> statistics could deal with projects which were already completed.  For
> instance: how many projects were completed the last year?  Or: what is
> the average amount of time spent per project until it's completed?

OK, I think that's clearer now.  That kind of statistic was not
possible at all in ETT, so I'll have to design it from scratch, but it
sounds good.

> If you find actions that are difficult to represent in the usage
> pattern you envisioned for ETT, we can have two separate workflows
> supported by timeclock: one workflow for which timeclock was
> originally designed, where it tracks "work hours"; the other where it
> tracks everything.  We could have the type of the workflow described
> in the COMMENT of the 'i' entry.  Or we could ask the user up front to
> specify which workflow is intended, and have that encoded in the
> header line of the timelog file (if we think these two workflows are
> mutually exclusive).

I was thinking about something like that, too.  Basically,
timeclock-modern, as it is designed right now, should ideally make
three main additions to stock timeclock:

1. A parser to retrieve information from the timelog file
2. Advanced statistic reports
3. A new optional workflow where it is able to track everything

Point 1 must explicitly support the current state of things, as it
would be useless otherwise.  Point 2 also should support the default
behaviour of timeclock, so all users can benefit from it; however,
some things such as tags are not supported out-of-the-box as of now,
while other things such as the 'b' or 'h' keywords don't make much
sense for the new behaviour.  So, statistic reports will depend on
what workflow the user chooses.

As for point 3, it is the most complex one because I haven't come to a
clear solution of how to implement it properly yet.  For now, I think
a user option which redefines the behaviour of some commands such as
timeclock-in and timeclock-out is the best path to follow.  And the
thing is, the new workflow will probably slightly modify the timelog
format.  Currently, my custom tm-clock-in (which would be the new
'timeclock-in' once the user opts-in into the new worflow) gets rid of
the letter code altogether, somehow breaking backward compatibility.
Maybe that's not a bad thing though, because if the user opted into
the new workflow, they probably don't care about that.

> I have only ever used timeclock in a very simple workflow, with a
> single "project" into which I was clocking in and then clocking out
> every day.  So my timelog file is a series of 'i's and 'o's, something
> that you can easily generate yourself.  If specific issues are of
> interest, please ask more specific questions.

Yes, I have tested that kind of timelogs and everything has gone well.
I was thinking on sligthly more complex files, maybe with 'O', 'h' and
'b' here or there.  Maybe I'm exaggerating a little, but it feels
wrong to not test it with real timelogs :)

> Why "worse"?  Can't we do this in a backward-compatible manner, like
> based on user options?  And if worse comes to worst, we can add a
> whole new set of commands to support the "track everything" workflow
> you had in mind for ETT.

Now that I think about it, maybe modifying timeclock-in in order to
support that workflow based on user options is a good idea.  That way
I don't have to support a separate tm-clock-in.  That's also another
argument in favour of forking timeclock instead of developing a
separate file.  I'll look into that.

> John Wiegley, the original author is somewhat busy these days, but we
> can add him to this discussion right away.  Here, done.

Thank you.