The reportmode report does not count the running clock

The reportmode report does not count the running clock

[François Pinard]

Hi, Org people.

I'm noticing that the R (org-agenda-clockreport-mode) command with the
*Org Agenda* buffer ignores the running clock.

To get a result closer to the truth while I work, I have to clock-out
and clock-in, then retry R.  (Then edit out the spurious clock out and
the following clock-in, to get rid of the short clocking gap.)

Could the running clock merely be added / counted in the report?

François

Re: The reportmode report does not count the running clock

[Bernt Hansen]

pinard@iro.umontreal.ca (François Pinard) writes:

> Hi, Org people.
>
> I'm noticing that the R (org-agenda-clockreport-mode) command with the
> *Org Agenda* buffer ignores the running clock.
>
> To get a result closer to the truth while I work, I have to clock-out
> and clock-in, then retry R.  (Then edit out the spurious clock out and
> the following clock-in, to get rid of the short clocking gap.)
>
> Could the running clock merely be added / counted in the report?

See the variable

;; Include current clocking task in clock reports
(setq org-clock-report-include-clocking-task t)

Regards
Bernt

Re: The reportmode report does not count the running clock

[François Pinard]

Bernt Hansen <bernt@norang.ca> writes:
> pinard@iro.umontreal.ca (François Pinard) writes:

>> I'm noticing that the R (org-agenda-clockreport-mode) command with the
>> *Org Agenda* buffer ignores the running clock.

> ;; Include current clocking task in clock reports
> (setq org-clock-report-include-clocking-task t)

Isn't that nice! :-)  Thanks again, Bernt.

The variable is not referred to in the Org mode manual (version 7.7
here).  It might be a good idea to include it.

François

Re: The reportmode report does not count the running clock

[Bernt Hansen]

pinard@iro.umontreal.ca (François Pinard) writes:

> Bernt Hansen <bernt@norang.ca> writes:
>> pinard@iro.umontreal.ca (François Pinard) writes:
>
>>> I'm noticing that the R (org-agenda-clockreport-mode) command with the
>>> *Org Agenda* buffer ignores the running clock.
>
>> ;; Include current clocking task in clock reports
>> (setq org-clock-report-include-clocking-task t)
>
> Isn't that nice! :-)  Thanks again, Bernt.
>
> The variable is not referred to in the Org mode manual (version 7.7
> here).  It might be a good idea to include it.
>
> François
It isn't?  Oops.  I'll prepare a patch for this.

Thanks,
Bernt

Re: The reportmode report does not count the running clock

[Carsten Dominik]

On 13.12.2011, at 16:30, Bernt Hansen wrote:

> pinard@iro.umontreal.ca (François Pinard) writes:
> 
>> Bernt Hansen <bernt@norang.ca> writes:
>>> pinard@iro.umontreal.ca (François Pinard) writes:
>> 
>>>> I'm noticing that the R (org-agenda-clockreport-mode) command with the
>>>> *Org Agenda* buffer ignores the running clock.
>> 
>>> ;; Include current clocking task in clock reports
>>> (setq org-clock-report-include-clocking-task t)
>> 
>> Isn't that nice! :-)  Thanks again, Bernt.
>> 
>> The variable is not referred to in the Org mode manual (version 7.7
>> here).  It might be a good idea to include it.
>> 
>> François
> It isn't?  Oops.  I'll prepare a patch for this.

Note that there is a million variables which are not referred to
in the manual - simply too many to mention them all.  It might be
useful to mentions this one, otherwise I would urge restraint.

A good way to find unknown variables is described here:

http://orgmode.org/worg/org-tutorials/org-customize.html

- Carsten

[PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Bernt Hansen]

Add reference to this variable when describing the agenda clock report.
---

Here's the documentation patch.  I won't be offended if you decide not
to apply it since we don't document every customizable variable in
org-mode.

Regards,
Bernt

 doc/org.texi |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 93c8c5a..04fa199 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -7969,6 +7969,7 @@ press @kbd{v a} again.
 @c
 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
 @vindex org-agenda-start-with-clockreport-mode
+@vindex org-clock-report-include-clocking-task
 Toggle Clockreport mode.  In Clockreport mode, the daily/weekly agenda will
 always show a table with the clocked times for the timespan and file scope
 covered by the current agenda view.  The initial setting for this mode in new
@@ -7976,7 +7977,8 @@ agenda buffers can be set with the variable
 @code{org-agenda-start-with-clockreport-mode}.  By using a prefix argument
 when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
 contributions from entries that are hidden by agenda filtering@footnote{Only
-tags filtering will be respected here, effort filtering is ignored.}.
+tags filtering will be respected here, effort filtering is ignored.}.  See
+also the variable @code{org-clock-report-include-clocking-task}.
 @c
 @orgkey{v c}
 @vindex org-agenda-clock-consistency-checks
-- 
1.7.8

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Bastien]

Bernt Hansen <bernt@norang.ca> writes:

> Add reference to this variable when describing the agenda clock
> report.

Applied, thanks.

> Here's the documentation patch.  I won't be offended if you decide not
> to apply it since we don't document every customizable variable in
> org-mode.

I think this one is important.

Thanks,

-- 
 Bastien

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Bernt Hansen]

Bastien <bzg@altern.org> writes:

> Bernt Hansen <bernt@norang.ca> writes:
>
>> Add reference to this variable when describing the agenda clock
>> report.
>
> Applied, thanks.

Thanks - I think...  I'm not sure what happened to my subject line on
that patch but I obviously blew that badly :(

Too late now...

Regards,
Bernt

Re: The reportmode report does not count the running clock

[François Pinard]

Hello, everybody.  Let me wish you all that the Year Started Well, and
will continue that way all along!

Carsten Dominik <carsten.dominik@gmail.com> writes:

> On 13.12.2011, at 16:30, Bernt Hansen wrote:
>>>> (setq org-clock-report-include-clocking-task t)
>> It isn't [referred to in the Org mode manual]?  Oops.  I'll prepare a
>> patch for this.

> Note that there is a million variables which are not referred to
> in the manual - simply too many to mention them all.

A million?  You *always* exaggerate! :-)

> It might be useful to mentions this one, otherwise I would urge
> restraint.  A good way to find unknown variables is described here:
> http://orgmode.org/worg/org-tutorials/org-customize.html

The manual should be reference, and should mention all variables.  A
textual search in the manual should yield anything worth finding.
However nicely and carefully the customization has been organized, one
should ideally not have to guess and retry customize branches in hope of
finding something, or peruse the sources, after having tried the manual.

Do not misread me, I'm not at all saying that there is something wrong
with the customization, or the availability of the sources! :-)

Maybe an appendix to the manual could be mechanically generated out of
all customization information, with some Makefile/Emacs machinery for
keeping it up-to-date?  Easier said than done, I know...  But I would
like at least to throw the idea in the field.

François

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Sebastien Vauban]

Hi Bastien,

Bastien wrote:
> Bernt Hansen <bernt-CNteSEi18yz3fQ9qLvQP4Q@public.gmane.org> writes:
>
>> Add reference to this variable when describing the agenda clock
>> report.
>
> Applied, thanks.
>
>> Here's the documentation patch.  I won't be offended if you decide not
>> to apply it since we don't document every customizable variable in
>> org-mode.
>
> I think this one is important.

This one appears important because its default value is not set as one would
or could expect. Shouldn't we set it to `t' by default?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Bastien]

Hi Sébastien,

"Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> writes:

> This one appears important because its default value is not set as one would
> or could expect. Shouldn't we set it to `t' by default?

I can see two use cases for clock reports: transient reports (for quick
checks about time spent) and persistent reports (for the boss.)  I guess
the second use case is the most common one, so excluding running clocks
by default (setq `org-clock-report-include-clocking-task' nil) looks ok
to me.

-- 
 Bastien

Re: The reportmode report does not count the running clock

[Bastien]

Hi François,

pinard@iro.umontreal.ca (François Pinard) writes:

> Hello, everybody.  Let me wish you all that the Year Started Well, and
> will continue that way all along!

Thanks!

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> Note that there is a million variables which are not referred to
>> in the manual - simply too many to mention them all.
>
> A million?  You *always* exaggerate! :-)

Well, I counted more than 1070 variables...  describing 5 of them 
per page would take 214 pages.  Not something I'd like to read :)

>> It might be useful to mentions this one, otherwise I would urge
>> restraint.  A good way to find unknown variables is described here:
>> http://orgmode.org/worg/org-tutorials/org-customize.html
>
> The manual should be reference, and should mention all variables.  A
> textual search in the manual should yield anything worth finding.

Emacs is The All-Mighty Self-Documenting Editor ;)

Wrt documentation, Emacs is its own reference, by letting you access
everything with C-h v org-*.

The manual is a secondary reference: one that contains the most useful
things to know about Org to use it efficiently.  It should cover 100% of
the core feature, and most of the rest -- but there is a trade-off in
this last area.  Between readability and completeness.

> However nicely and carefully the customization has been organized, one
> should ideally not have to guess and retry customize branches in hope of
> finding something, or peruse the sources, after having tried the manual.
>
> Do not misread me, I'm not at all saying that there is something wrong
> with the customization, or the availability of the sources! :-)

Another point: there is a lot to do to improve the current docstrings
and the manual.  This is a matter of 1) pulling from git, 2) modifying
the file, 3) run `C-x v =' in the buffer, 4) send the patch.

:)

> Maybe an appendix to the manual could be mechanically generated out of
> all customization information, with some Makefile/Emacs machinery for
> keeping it up-to-date?  Easier said than done, I know...  But I would
> like at least to throw the idea in the field.

This crossed my mind recently. 

See this file: http://lumiere.ens.fr/~guerry/u/org.org
which presents all functions/options/variables from some org*el 
files.  

The code to produce this is here:
http://lumiere.ens.fr/~guerry/u/org-lto.el

This is broken in many respect -- no cleanup is done on the 
docstring, and there is nearly no formatting.  Also, it does not
export well (see http://lumiere.ens.fr/~guerry/u/org.html)

If you're interested in improving this, please go ahead, I'd be
interested in getting something working along these lines.

Best regards,

-- 
 Bastien

Re: The reportmode report does not count the running clock

[François Pinard]

Bastien <bzg@altern.org> writes:

> Hi François,

>> Carsten Dominik <carsten.dominik@gmail.com> writes:

>>> Note that there is a million variables which are not referred to
>>> in the manual - simply too many to mention them all.
>> A million?  You *always* exaggerate! :-)

> Well, I counted more than 1070 variables...  describing 5 of them 
> per page would take 214 pages.  Not something I'd like to read :)

That's why I suggested an appendix.  We search in them, more than we
really read them.  On the other hand, it would considerably augment the
weight of a printed manual, and so, be more harmful to our forests.

> Wrt documentation, Emacs is its own reference, by letting you access
> everything with C-h v org-*.

Emacs has impressive ways to offer its own documentation.  Still a bit
uneasy to use C-h v (or C-h f) on everything.  M-x apropos org- RET is
more handy and searchable, yet the documentation is likely limited to
the first line of each docstring (so at least this convention for a
complete sentence in the first line of a docstring).

> Another point: there is a lot to do to improve the current docstrings
> and the manual.  This is a matter of 1) pulling from git, 2) modifying
> the file, 3) run `C-x v =' in the buffer, 4) send the patch.  [...]
> If you're interested in improving this, please go ahead, I'd be
> interested in getting something working along these lines.

Oh, the problem is surely not the lack of interest, but the sore lack of
free hours in a week, and the quantity of ways to occupy those rare
hours already (something Org mode is tremendously helpful at organizing,
by the way).  Surely that given enough free time, I would just love to
contribute.  The truth is that I can only offer tiny crumbs.  In any
case, I'm saving your message and notes (who knows the future!).

François

Re: The reportmode report does not count the running clock

[Bastien]

Hi François,

pinard@iro.umontreal.ca (François Pinard) writes:

> That's why I suggested an appendix.  We search in them, more than we
> really read them.  On the other hand, it would considerably augment the
> weight of a printed manual, and so, be more harmful to our forests.

That's why I tried to gather *all* functions and variables in an .org
file, which you can see as an appendix.  Did you check it?

>> Wrt documentation, Emacs is its own reference, by letting you access
>> everything with C-h v org-*.
>
> Emacs has impressive ways to offer its own documentation.  Still a bit
> uneasy to use C-h v (or C-h f) on everything.  M-x apropos org- RET is
> more handy and searchable, yet the documentation is likely limited to
> the first line of each docstring (so at least this convention for a
> complete sentence in the first line of a docstring).
>
>> Another point: there is a lot to do to improve the current docstrings
>> and the manual.  This is a matter of 1) pulling from git, 2) modifying
>> the file, 3) run `C-x v =' in the buffer, 4) send the patch.  [...]
>> If you're interested in improving this, please go ahead, I'd be
>> interested in getting something working along these lines.
>
> Oh, the problem is surely not the lack of interest, but the sore lack of
> free hours in a week, and the quantity of ways to occupy those rare
> hours already (something Org mode is tremendously helpful at organizing,
> by the way).  

Org should claim 10% of the time it spares you ;-)

> Surely that given enough free time, I would just love to
> contribute.  The truth is that I can only offer tiny crumbs.  In any
> case, I'm saving your message and notes (who knows the future!).

Indeed.  My suggestion is to stick to the current collective workflow:
let's try to document small things in relevant places (manual or worg)
and let's avoid Big Projects (bikesheds).

Thanks!

-- 
 Bastien

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[Bernt Hansen]

"Sebastien Vauban"
<wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> writes:

> Hi Bastien,
>
> Bastien wrote:
>> Bernt Hansen <bernt-CNteSEi18yz3fQ9qLvQP4Q@public.gmane.org> writes:
>>
>>> Add reference to this variable when describing the agenda clock
>>> report.
>>
>> Applied, thanks.
>>
>>> Here's the documentation patch.  I won't be offended if you decide not
>>> to apply it since we don't document every customizable variable in
>>> org-mode.
>>
>> I think this one is important.
>
> This one appears important because its default value is not set as one would
> or could expect. Shouldn't we set it to `t' by default?

The default value was set as is so that behaviour didn't change before
this variable and related code was introduced.  The clock reports never
used to consider the current clocking item before this patch went in.
It may very well make more sense to turn it on by default.

Regards,
Bernt

Re: The reportmode report does not count the running clock

[François Pinard]

Bastien <bzg@altern.org> writes:

> Hi François,

Hi, Bastien, and everybody.  (By the way, in "Carsten Dominik", may I
assume that "Carsten" is the first name and "Dominik" the family name?
What is the nationality?)

> That's why I tried to gather *all* functions and variables in an .org
> file, which you can see as an appendix.  Did you check it?

Not yet, I'll come to it for sure.

> Org should claim 10% of the time it spares you ;-)

Absolutely.  This is why I initially got involved in GNU, long ago.  It
was absolutely normal to me that I repay the Emacs (and GCC, and Make,
and Bison) author for all the increased productivity and saved time.  (I
honestly think I amply filled my debt, so I'm comfortable.)

By the way, long ago, I signed a generic FSF document for all past,
present and future work for any free software project related to GNU.
Hopefully, it is still valid and I am free from any later paperwork.
(Yet, Richard may decide strange things once in a while.)

> My suggestion is to stick to the current collective workflow: let's
> try to document small things in relevant places (manual or worg) and
> let's avoid Big Projects (bikesheds).

I will not tackle big Org projects unless I really think I'll have
enough free time to finish them :-).

François

Re: [PATCH] * doc/org.texi (Agenda commands): Document org-clock-report-include-clocking-task

[François Pinard]

Bastien <bzg@altern.org> writes:

> "Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> writes:

>> This one appears important because its default value is not set as
>> one would or could expect. Shouldn't we set it to `t' by default?

> I can see two use cases for clock reports: transient reports (for
> quick checks about time spent) and persistent reports (for the boss.)
> I guess the second use case is the most common one, so excluding
> running clocks by default (setq
> `org-clock-report-include-clocking-task' nil) looks ok to me.

Hmph!

The first case is really the most common one, in my experience at least.
I check my times every day, sometimes many times a day.  The boss only
needs them every few weeks.

Org mode is primarily for me, quite secondarily for the boss or anyone
else, the defaults should probably be tuned according to this principle.

François

Re: The reportmode report does not count the running clock

[François Pinard]

Bastien <bzg@altern.org> writes:

> Hi François,

> See this file: http://lumiere.ens.fr/~guerry/u/org.org which presents
> all functions/options/variables from some org*el files.  The code to
> produce this is here: http://lumiere.ens.fr/~guerry/u/org-lto.el.

Interesting, thanks for sharing.

> This is broken in many respect -- no cleanup is done on the 
> docstring, and there is nearly no formatting.  Also, it does not
> export well (see http://lumiere.ens.fr/~guerry/u/org.html)

This is a consequence from using lists, for which formatting is more
limited (so far that I know).

> If you're interested in improving this, please go ahead, I'd be
> interested in getting something working along these lines.

OK, I'll likely be back on this, yet not imminently.

François