all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Extending timeclock.el
@ 2023-05-05 19:15 John Task
  2023-05-06  6:09 ` Philip Kaludercic
  2023-05-06  7:19 ` Eli Zaretskii
  0 siblings, 2 replies; 18+ messages in thread
From: John Task @ 2023-05-05 19:15 UTC (permalink / raw)
  To: emacs-devel

Hello.  A little context, first; some days ago, I submitted a request
for including a package in the NonGNU ELPA repository.  The package in
question was a time tracker named ETT.  However, Eli pointed out that
instead of creating a new package I could, for instance, extend the
built-in timeclock.el instead.  To be honest, I didn't like the idea
at first, but looking at the code I quickly realized it wouldn't be
that hard.  At least, not as dramatically hard as I thought.

So I started this: https://gitlab.com/q01_code/timeclock-modern

[This wasn't my first name choice, but turns out timeclock-x is
already taken]

So far, I managed to write a series of parsers for the timelog format,
as well as a basic API for retrieving information from it.  This
should allow me to port all the relevant code from ETT without issues.
However, I'm not really familiarized with timeclock, so I can't assert
my design choices so far have been ideal.

+ The letter code at the start of every line was the most difficult
part.  ETT (and a lot of modern time trackers as well) don't
understand what clock-out means, as the idea is to clock everything;
the user just clocks-in different activities.  So, I dropped 'i' and
'o' for my custom tm-clock-in altogether.  As for the parser, it
understands 'o' as the start of a so-named 'Untracked' item/project.
That way it can read existent timelogs just fine.  This is hard
enough, but turns out there are also other codes ('h', 'b' and '0').
I interpret '0' as an 'o' and ignore the other ones, but I'm not sure
if this is correct.

+ As I make a lot of decisions such as the last one from ignorance,
I'm clueless about how well the parser (and the API) works for real
timelog files.  If anybody wants to test that, it would be
appreciated.

+ As the original timeclock-in doesn't support inputting tags (as well
as other features I need), I wrote a custom tm-clock-in.  But I'm not
sure if this is the right approach.  And redefining timeclock-in would
be even worse, for sure.

I'll eventually contact the original author as well, but I wanted to
know of any other opinions here first.

Best regards.



^ permalink raw reply	[flat|nested] 18+ messages in thread
* Re: Extending timeclock.el
@ 2023-05-06 15:47 John Task
  2023-05-06 16:53 ` Eli Zaretskii
  0 siblings, 1 reply; 18+ messages in thread
From: John Task @ 2023-05-06 15:47 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 18+ messages in thread
* Re: Extending timeclock.el
@ 2023-05-06 16:46 John Task
  0 siblings, 0 replies; 18+ messages in thread
From: John Task @ 2023-05-06 16:46 UTC (permalink / raw)
  To: Philip Kaludercic; +Cc: emacs-devel

Philip Kaludercic <philipk@posteo.net> writes:

> By whom?  I couldn't find anything.

https://www.emacswiki.org/emacs/download/timeclock-x.el

It's referenced by several people.  It's not really popular, but I
don't like name conflicts :)

Best regards.



^ permalink raw reply	[flat|nested] 18+ messages in thread
* Re: Extending timeclock.el
@ 2023-05-06 18:35 John Task
  0 siblings, 0 replies; 18+ messages in thread
From: John Task @ 2023-05-06 18:35 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

Eli Zaretskii <eliz@gnu.org> writes:

> The way we extend existing packages is by adding code to the existing
> files, not by starting new FOO-x.el files.  This is a natural way of
> extending them, even if the extension adds something that is only
> loosely coupled with the previous functionalities.

Noted, thanks.

> I'm not sure this is being used.  Do you see any code that logs "b"
> lines in the file?

Interesting.  I looked at the code and it seems that nothing logs "b"
lines in the file.  Maybe it was removed?  Anyway, I think I can
safely ignore it then.

> I'm guessing that this means you move the log file to some archive,
> e.g., when a year ends or something.

Yes, that makes sense.  Though archiving log files doesn't seem too
statistic-friendly...  Maybe I'll have to warn about that somewhere.

> You don't have to design and implement anything that didn't exist
> unless you think it's a must-to-have feature.  We can always wait for
> users to request such a feature in some distant future.  What I
> described was just a rationale for having "O", and my point was that
> allowing people to say the project is finished is useful even if for
> now this is largely unused.

OK.

> As I said, the timelog file could announce what kind it is of.

Yes, that would be a solution.  I implemented a safe comment string
already, so something like #+FORMAT: should do the trick.

> You can build tests using the ert package.  We use it in our test
> suite (under the test/ subdirectory of the Emacs source tree).

Good.  I'll look into that.



^ permalink raw reply	[flat|nested] 18+ messages in thread
* Re: Extending timeclock.el
@ 2023-05-06 19:21 John Task
  0 siblings, 0 replies; 18+ messages in thread
From: John Task @ 2023-05-06 19:21 UTC (permalink / raw)
  To: John Wiegley; +Cc: emacs-devel

John Wiegley <johnw@gnu.org> writes:

> Hi fellow John

Hello.  Thanks for the quick reply.

> If you do extend the _format_, it's likely you may break some of the other
> tools that process timelog data. So if you choose to make an enriched format,
> it would be useful if you provided a way to export this data back to flat
> timelog form (such as by stripping comments). Then I could go from
> timeclock-modern format -> timeclock format -> ledger, for example.

I have thought about this issue, too.  In principle, the format should
remain unchanged _unless_ the user opts into the new workflow I'll
add, which indeed is not backward compatible.  If the user doesn't do
so, the only new thing will be statistic reports and a parser they can
use with their existent timelog files, again without any changes.

Regarding the export option, I haven't thought about that, but it
should be feasible.  So, if you think users who opt into the new
behaviour would also like to retain a way to use that data with
existent tools, I'll work in that.  But keep in mind that such data
could be pretty different to that of other timeclock users, because
they won't track, say, 8 hours per day, but rather pretty much
everything they do.

Best regards.



^ permalink raw reply	[flat|nested] 18+ messages in thread

end of thread, other threads:[~2023-05-09 16:44 UTC | newest]

Thread overview: 18+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-05-05 19:15 Extending timeclock.el John Task
2023-05-06  6:09 ` Philip Kaludercic
2023-05-06  7:19 ` Eli Zaretskii
2023-05-06 18:35   ` John Wiegley
2023-05-06 18:48     ` Ihor Radchenko
2023-05-06 18:48       ` John Wiegley
2023-05-06 19:02         ` Ihor Radchenko
2023-05-06 19:00           ` John Wiegley
2023-05-06 19:09       ` Eli Zaretskii
2023-05-06 19:22         ` Ihor Radchenko
2023-05-06 19:23           ` John Wiegley
2023-05-06 22:10   ` Mike Kupfer
2023-05-09 16:44     ` Mike Kupfer
  -- strict thread matches above, loose matches on Subject: below --
2023-05-06 15:47 John Task
2023-05-06 16:53 ` Eli Zaretskii
2023-05-06 16:46 John Task
2023-05-06 18:35 John Task
2023-05-06 19:21 John Task

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.