2023-04-22 Org mode clock table for the last week

Some time ago I mentioned that I started doing “weekly reviews” of what I have done last week and what I am going in the next week. One part of my weekly reviews is checking how much time I spent doing various things last week. Of course, Org mode clock tables are an excellent tool for that.

There is one caveat, though. What does “a week” mean? It turns out that it is not obvious at all. The main problem here is the :wstart parameter, telling what day is the first day of the week.

The Org mode default is 1, which means Monday. This is in accordance with the Polish custom of starting weeks on Mondays. (I suppose the reason for this defalt is the European provenance of Org mode.) However, I have good reasons to use Sunday as the starting day of the week. One of them is my principles – as a Catholic, I consider Sunday the most important day of the week (and in a sense, the most important day in the history of the world!), and Monday is merely feria secunda for me. Another reason is purely pragmatic – I do my weekly review on Sunday morning, so “last week” means “from the last Sunday to yesterday” for me.

Now, Org mode clock tables can show the time I spent on various things in a week (thisweek or lastweek or thisweek±N etc.), and with :wstart set to 1 for Monday by default. (By the way, you can define any day of the week to be the starting day, but come on, who’s going to treat Wednesday as the first day?) So I should definitely use :wstart 0 – but what is thisweek on Sunday if the week starts on Sunday? Is it the week starting today or the last Sunday? In my opinion, it should be the one starting today, but it seemed to me that Org mode did not work that way.

Since the manual does not say (and this is not a criticism of the manual – it is probably outside its scope to define subtle calendar notions!), I decided to do some experimenting. And the results were rather strange. Apparently on Sundays thisweek starts a week (or less) ago, but never “today” – even if :wstart is set to 0. What is going on here?

I asked on the Org mode mailing list, and it seems that I know the solution now. The manual says:
`:wstart’ The starting day of the week. The default is 1 for Monday.
and I assumed that I should use 0 for Sunday (which is logical and consistent with how calendar-week-start-day works). It turns out that when I set it to 7 instead, the table works exactly as expected.

This is certainly unexpected for me, and hence I’d say it’s a bug. I hope it will be fixed in a future version of Org mode. For now, I just need to remember to use :wstart 7.

While at that, I also learned that while you can use week in the clock table definition, it is much better to use thisweek instead. The reason is that org-clocktable-shift (invoked by S-<left> and S-<right> when the point is the #+BEGIN: clocktable line) only works with this.* blocks. (To be fair, while using week, month etc. as :block works, it is not documented, so I cannot blame anyone for telling me to use it!) And interestingly, you can also say thisq (or thisq±N, or lastq to mean thisq-1) for quarters, even though this is not mentioned in the manual.

So, I finally solved the mystery of weeks behaving in a weird way in clock tables, learning some Org mode tidbits I’d prefer not to know along the way… Still, these quirks do not diminish the usefulness and overall greatness of Org mode for me!

CategoryEnglish, CategoryBlog, CategoryEmacs