Uwe Brauer <o...@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.yanta...@posteo.net> From: Ihor Radchenko <yanta...@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 <o...@mat.ucm.es> Link: https://orgmode.org/list/87h6z2c8pf....@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>
