Extending timeclock.el

Extending timeclock.el

[John Task]

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.

Re: Extending timeclock.el

[Philip Kaludercic]

John Task <q01@disroot.org> writes:

> 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]

By whom?  I couldn't find anything.

> 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.

-- 
Philip Kaludercic

Re: Extending timeclock.el

[Eli Zaretskii]

> From: John Task <q01@disroot.org>
> Date: Fri, 05 May 2023 16:15:02 -0300
> 
> 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

Thank you very much for working on extending timeclock.

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

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.

> 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.

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?

> + 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.

The codes are documented in the doc string of timeclock-log-data
(assuming it is up-to-date ;-).  There's no "0" there that I could
see, but there is "O" (upper-case letter O).

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?

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).

> + 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.

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.

> + 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.

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.

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

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

Re: Extending timeclock.el

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

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

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

Hi fellow John, I'm happy to hear you're thinking of extending timeclock. It
only ever strived to be the most basic form of data collection possible, with
the hope that other functionality and UIs could be built on top of it. My
ledger tool, for example, directly reads timelog files in order to provide
reports summarized by week, month, account, etc.

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.

Otherwise, I'm available here by e-mail, and always happy to provide context
that may help with your decision making. Best of luck with getting this new
code ultimately into Emacs or ELPA!

--
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Extending timeclock.el

[Ihor Radchenko]

John Wiegley <johnw@gnu.org> writes:

> 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.

Ideally, one should be able to customize how to parse and write the
format. Then, exporting/importing will just amount for calling
different writer and parser function.

(AFAIU, the data is recorded using some standard internal data structure
already)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Extending timeclock.el

[John Wiegley]

>>>>> Ihor Radchenko <yantar92@posteo.net> writes:

> Ideally, one should be able to customize how to parse and write the format.
> Then, exporting/importing will just amount for calling different writer and
> parser function.

The only provisor being that certain external tools depend on the format being
written in the original timelog style. So those tools may need adapted parsers
as well, if you use a custom writer from Emacs.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Extending timeclock.el

[Ihor Radchenko]

John Wiegley <johnw@gnu.org> writes:

> The only provisor being that certain external tools depend on the format being
> written in the original timelog style. So those tools may need adapted parsers
> as well, if you use a custom writer from Emacs.

I imagine that timeclock.el itself can be used to convert to standard
format for external tools: custom reader -> internal db -> standard
writer.

The main reason I am mentioning pluggable parsers/writers is potential
to integrate things with Org.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Extending timeclock.el

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 403 bytes --]

Ah, that’s a good thought, Ihor. I agree.

John

> On May 6, 2023, at 12:02 PM, Ihor Radchenko <yantar92@posteo.net> wrote:
> 
> I imagine that timeclock.el itself can be used to convert to standard
> format for external tools: custom reader -> internal db -> standard
> writer.
> 
> The main reason I am mentioning pluggable parsers/writers is potential
> to integrate things with Org.


[-- Attachment #2: Type: text/html, Size: 4237 bytes --]

Re: Extending timeclock.el

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, John Task <q01@disroot.org>,
>  emacs-devel@gnu.org
> Date: Sat, 06 May 2023 18:48:26 +0000
> 
> John Wiegley <johnw@gnu.org> writes:
> 
> > 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.
> 
> Ideally, one should be able to customize how to parse and write the
> format.

Doesn't make a lot of sense to me: the timelog file is the internal
implementation detail of timeclock.el, and doesn't need to support
user customization of the format.

Re: Extending timeclock.el

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Ideally, one should be able to customize how to parse and write the
>> format.
>
> Doesn't make a lot of sense to me: the timelog file is the internal
> implementation detail of timeclock.el, and doesn't need to support
> user customization of the format.

It is not, AFAIU. As John Wiegley pointed, it is already used by GNU
ledger.

And wouldn't it be nice to allow timeclock to read from Org logbooks or
some third-party timelog file formats?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Extending timeclock.el

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 601 bytes --]

Just a quick clarification: Ledger is not a part of the GNU project, it’s a endeavor I started under the BSD (or MIT?) license that is currently being maintained by several people.

But that’s neither here nor there. Weather timeclock.el should be the junction point for going to and from other timelog formats is another question. It’s really a _very_ basic format: in, out, with optional “project closing out”.

John

> On May 6, 2023, at 12:22 PM, Ihor Radchenko <yantar92@posteo.net> wrote:
> 
> It is not, AFAIU. As John Wiegley pointed, it is already used by GNU
> ledger.


[-- Attachment #2: Type: text/html, Size: 2359 bytes --]

Re: Extending timeclock.el

[Mike Kupfer]

Eli Zaretskii wrote:

> 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", 

Well, timeclock also uses 'o' with timeclock-change, as in

i 2023/04/25 10:49:35 task1
o 2023/04/25 11:10:15
i 2023/04/25 11:10:17 task2
o 2023/04/25 11:45:41
i 2023/04/25 11:45:44 task3
o 2023/04/25 12:10:33
i 2023/04/25 12:10:35 task2
o 2023/04/25 12:35:14

(This is an excerpt from my timelog file, with the task names
genericized.)

I think the multi-second gaps between "o" and "i" are from timeclock
writing the "o" line and then prompting for the new task name.  It seems
like timelock could get the new task name first, and then write out the
"o" and "i" lines with the same timestamp.

mike

Re: Extending timeclock.el

[Mike Kupfer]

Mike Kupfer wrote:

> Well, timeclock also uses 'o' with timeclock-change

I got an off-list reply to this from Davis Herring <herring@lanl.gov>.
Davis has some technical difficulties posting to emacs-devel, so I'm
posting some excerpts here, in case anyone would like to follow up with
him.

Davis wrote:

> Since we're talking about extending timeclock: I rewrote
> timeclock-change years ago to emit a single "c" line rather than have an
> "o" with no reason and an "i" (with a different time).  Part of the
> reason for this was to reduce the time spent reading the file: mine
> covers several years of work and is 30k lines with "c"s.
> 
> Obviously I'd be glad to contribute this if anyone else cares for it.

He also thought that "c" might be a better fit for the track-everything
workflow.

mike

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.

Re: Extending timeclock.el

[Eli Zaretskii]

> From: John Task <q01@disroot.org>
> Cc: emacs-devel@gnu.org
> Date: Sat, 06 May 2023 12:47:24 -0300
> 
> 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.

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.

> 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.

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

> Also, old log data can be archived?

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

> > 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.

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.

> 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

Yes.

> 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.

Right.

> 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.

If that works, I agree it's the best.

> 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.

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

> > 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 :)

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

> > 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.

Thanks.

Re: Extending timeclock.el

[John Task]

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.

Re: Extending timeclock.el

[John Task]

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.

Re: Extending timeclock.el

[John Task]

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.