Re: org-clock-report on headings and subheadings or for the whole file?

[Ihor Radchenko]

Uwe Brauer <oub@mat.ucm.es> writes:

>> This information is already in the docstring
>
>>     The new table inherits its properties from the variable
>>     org-clock-clocktable-default-properties.  The scope of the
>>     clocktable, when not specified in the previous variable, is
>>     subtree when the function is called from within a subtree, and
>>     file elsewhere.
>
>> Or do you think it can be expressed better?
>
> It is the term *subtree* that I find confusing.
>
>
> * Introduction
> ** Details
>
> <-- that is for me within a subtree
>
> * Introduction
> * Details
>
> <-- that is for me within a tree
>
> So why not
>
> The scope of the clocktable, when not specified in the previous
> variable, is subtree when the function is called from within a subtree
> or tree and file elsewhere. So if you want a clocktable for the whole
> file, you should call the function before the first heading.

What about the attached patch?

>From a5dff6d46044db868dd95f6b57c28dffb202c308 Mon Sep 17 00:00:00 2001
Message-Id: 
<a5dff6d46044db868dd95f6b57c28dffb202c308.1668476319.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Tue, 15 Nov 2022 09:35:47 +0800
Subject: [PATCH] org-clock-report: Improve docstring

* lisp/org-clock.el (org-clock-report): Clarify :scope when called
from inside a heading or before first heading.  Separate :scope
description into a separate paragraph.

Reported-by: Uwe Brauer <oub@mat.ucm.es>
Link: 87h6z2c8pf.fsf@mat.ucm.es">https://orgmode.org/list/87h6z2c8pf.fsf@mat.ucm.es
---
 lisp/org-clock.el | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index 9dacc050d..604b5481c 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -2146,10 +2146,12 @@ (defun org-clock-report (&optional arg)
 Otherwise, insert a new one.
 
 The new table inherits its properties from the variable
-`org-clock-clocktable-default-properties'.  The scope of the
-clocktable, when not specified in the previous variable, is
-`subtree' when the function is called from within a subtree, and
-`file' elsewhere.
+`org-clock-clocktable-default-properties'.
+
+The scope of the clocktable, when not specified in the previous
+variable, is `subtree' of the current heading when the function is
+called from inside heading, and `file' elsewhere (before the first
+heading).
 
 When called with a prefix argument, move to the first clock table
 in the buffer and update it."
-- 
2.35.1

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