[Orgmode] [PATCH] New clocktable-feature: Structure clocktable by tags rather than by hierarchy

[B Grobauer]

Hi,

at work I am required to specify what I have spent my time on by assigning
clocked time to one of several projects/accounts. To do so, the
clocktable-feature
of org-mode already is a tremendous help, but I found that I still had to
do quite a bit of manual work, because the structure of my org-files
does not correspond 1:1 with my projects.

The attached patch allows me to tag headings with project/account names
and then have clocktable generate a table that structures the clocked time
by these project names rather than by the hierarchical layout of the
org-files.

Here is what a clock-table for the attached clocktags_test.org
looks like without the new feature:


| L | Headline                            |        Time |        |      |
|---+-------------------------------------+-------------+--------+------|
|   | *Total time*                        |     *17:30* |        |      |
|---+-------------------------------------+-------------+--------+------|
|   |                                     | *FILE time* | *0:00* |      |
| 1 | Todos                               |        7:00 |        |      |
| 2 | DONE Unallocated Task               |             |   1:00 |      |
| 2 | DONE Some Task  for Project A       |             |   1:00 |      |
| 2 | DONE Some Task for Project B        |             |   1:00 |      |
| 2 | DONE Another Task for Project A     |             |   1:00 |      |
| 2 | DONE Antother Task for Project B    |             |   1:00 |      |
| 2 | DONE Yet another Task for Project A |             |   1:00 |      |
| 2 | DONE Yet antoher Task for Project B |             |   1:00 |      |
| 1 | Project A                           |        7:30 |        |      |
| 2 | Subproject A1                       |             |   4:30 |      |
| 3 | Task 1 for Subproject A1            |             |        | 2:00 |
| 3 | Task 2 for Subproject A1            |             |        | 1:00 |
| 3 | Task 3 for Subproject A1            |             |        | 1:00 |
| 2 | Subproject A2                       |             |   3:00 |      |
| 3 | Task 1 for Subproject A2            |             |        | 1:00 |
| 3 | Task 2 for Subproject A2            |             |        | 1:00 |
| 3 | Task 3 for Subproject A2            |             |        | 1:00 |
| 1 | Project B                           |        3:00 |        |      |
| 2 | Task 1 for Project B                |             |   1:00 |      |
| 2 | Task 2 for Project B                |             |   1:00 |      |
| 2 | Task 3 for Project B                |             |   1:00 |      |

Below is what it looks like with the new "clocktags" feature,
assuming that

- all tasks that pertain to project A have been tagged with
  "00Project_A" (possibly using tag inheritance)
- all tasks that pertain to project B have been tagged with
  "01Project_B" (possibly using tag inheritance)
- the clocktable is called with parameter ':clocktable "[0-9][0-9]"'
  where the parameter value specifies a regular expression which
  a tag has to match in order to be used for structuring
  the clocktable

| ClockTag    | L | Headline                              |    Time |
|-------------+---+---------------------------------------+---------|
|             |   | *Total time*                          | *17:30* |
|-------------+---+---------------------------------------+---------|
|-------------+---+---------------------------------------+---------|
| UNALLOCATED |   | *Total*                               |  *1:00* |
|-------------+---+---------------------------------------+---------|
|             | 2 | DONE Unallocated Task                 |    1:00 |
|-------------+---+---------------------------------------+---------|
| 00Project_A |   | *Total*                               | *10:30* |
|-------------+---+---------------------------------------+---------|
|             | 2 | DONE Some Task  for Project A         |    1:00 |
|             | 2 | DONE Another Task for Project A       |    1:00 |
|             | 2 | DONE Yet another Task for Project A   |    1:00 |
|             | 2 | Subproject A1                         |    0:30 |
|             | 3 | Task 1 for Subproject A1              |    1:00 |
|             | 4 | Subtask 1 of Task 1 for Subproject A1 |    1:00 |
|             | 3 | Task 2 for Subproject A1              |    1:00 |
|             | 3 | Task 3 for Subproject A1              |    1:00 |
|             | 3 | Task 1 for Subproject A2              |    1:00 |
|             | 3 | Task 2 for Subproject A2              |    1:00 |
|             | 3 | Task 3 for Subproject A2              |    1:00 |
|-------------+---+---------------------------------------+---------|
| 01Project_B |   | *Total*                               |  *6:00* |
|-------------+---+---------------------------------------+---------|
|             | 2 | DONE Some Task for Project B          |    1:00 |
|             | 2 | DONE Antother Task for Project B      |    1:00 |
|             | 2 | DONE Yet antoher Task for Project B   |    1:00 |
|             | 2 | Task 1 for Project B                  |    1:00 |
|             | 2 | Task 2 for Project B                  |    1:00 |
|             | 2 | Task 3 for Project B                  |    1:00 |

Note that the hierarchical structure of the table is gone --
it does not make sense here, because the times of
children are not necessarily added to the time of the parent:
the hierarchical structure does not have meaning anymore
as far as clocking is concerned. Having said that, of course
in many instances one will use the hierarchy by tagging
a top-level name with a project/account tag and then
use inheritance to have all children attributed to that project.

The feature also works for scope=agenda and pulls
together clocked times from all files for each "clocktag".

The patch is not a small one, because I had to factor
out the printing of the table into a function of its
own and construct the table information as an association
list rather than directly as a string. As a result, you now
also have the possibility to receive the collected information
of the clocktable as list structure when setting the parameter
"to_alist" to a non-nil value. This may be interesting if you
want to use the function org-dblock-write:clocktable from
another function rather than through the inteface for
dynamic blocks.

I have tried to extensively comment the changes I made
to org-clock.el in order to facilitate evaluation whether the
patch is fit for inclusion into the distribution.

The attached clocktags_test.org contains also examles
for using the step parameter and the output of clocktable
results as list structure for further use in other functions.

Let me close with expressing my deep gratitude to Carsten Dominik
and all contributors to orgmode for the fantastic orgmode
project: I have been using org-mode for two years now and
don't quite know how I managed without it before that...

Best regards,

Bernd

clocktags_test.org
Description: Lotus Organizer

clocktags.patch
Description: Binary data