branch: externals/org
commit 9e9cc1e300406b7759f2d7c1ea103069ae0dab0b
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
doc/org-manual.org: Improve description of summary types in column
attributes
* doc/org-manual.org (Column attributes): Clarify that: summary types
ignore property values of non-leaf nodes during computation; property
values in non-leaf nodes may be overwritten; special properties ignore
summary specification; CLOCKSUM and CLOCKSUM_T use special rules for
column estimates.
(Summaries in deeply nested hierarchy): Add an example showing how
summaries are computed hierarchically.
Reported-by: Alexander Adolf <alexander.ad...@condition-alpha.com>
Link:
https://list.orgmode.org/orgmode/d4f5e6e94a8b5b62463a8df8cb85e...@condition-alpha.com/
---
doc/org-manual.org | 74 ++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 66 insertions(+), 8 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 47248e18ae..f32d1271ee 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5736,10 +5736,22 @@ optional. The individual parts have the following
meaning:
- {{{var(SUMMARY-TYPE)}}} ::
- The summary type. If specified, the column values for parent nodes
- are computed from the children[fn:: If more than one summary type
- applies to the same property, the parent values are computed
- according to the first of them.].
+ The summary type. If specified, the column values for parent
+ headings are computed from the direct children. If there is any
+ existing property defined for the parent nodes, it is not used in
+ the calculations.
+
+ When there is an existing property in parent heading, Org does not
+ only overlay the computed value in the column view, but also
+ overwrites the property value in parent's property drawer[fn:: If
+ more than column definition is requested for the same property, only
+ the first definition will trigger writing to the property drawer.
+ For example, =%EFFORT{mean} %EFFORT(Sum){:}= will write the mean
+ value of =EFFORT= property; not the sum. If the first column
+ definition does not have summary type (=%EFFORT %EFFORT{mean}=),
+ nothing will be written to the property drawer].
+
+ Summary type is ignored for special properties.
Supported summary types are:
@@ -5790,7 +5802,7 @@ constraints.].
#+begin_example
:COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \
- %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
+ %10Time_Estimate{:}
:Owner_ALL: Tammy Mark Karl Lisa Don
:Status_ALL: "In progress" "Not started yet" "Finished" ""
:Approved_ALL: "[ ]" "[X]"
@@ -5808,9 +5820,55 @@ all values. The =Approved= column does have a modified
title
(=Approved?=, with a question mark). Summaries are created for the
=Time_Estimate= column by adding time duration expressions like HH:MM,
and for the =Approved= column, by providing an =[X]= status if all
-children have been checked. The =CLOCKSUM= and =CLOCKSUM_T= columns
-are special, they list the sums of CLOCK intervals in the subtree,
-either for all clocks or just for today.
+children have been checked.
+
+The =CLOCKSUM= and =CLOCKSUM_T= column properties are special, they
+list the sums of =CLOCK:= intervals in the subtree, either for all
+clocks (=CLOCKSUM=) or just for today (=CLOCKSUM_T=). Unlike =:=
+summary type that ignores property values in parent headings, all the
+=CLOCK:= intervals are summed up, including =CLOCK:= lines within
+parent headings.
+
+***** Summaries in deeply nested hierarchy
+
+When computing summaries of deeply nested headings, the summaries are
+computed recursively, from the deepest level to the shallowest. Here
+is an example:
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM %EFFORT{:mean}" :id global
+| ITEM | EFFORT |
+|--------------------+---------|
+| Top level | 3h 0min |
+| \_ Intermediate 1 | 1h 0min |
+| \_ Leaf 1 | 1h |
+| \_ Leaf 2 | 1h |
+| \_ Leaf 3 | 1h |
+| \_ Intermediate 2 | 5h |
+,#+END:
+
+,* Top level
+,** Intermediate 1
+:PROPERTIES:
+:EFFORT: *unused*, will be set to 1h 0min (mean of the leaf nodes)
+:END:
+,***** Leaf 1
+:PROPERTIES:
+:EFFORT: 1h
+:END:
+,*** Leaf 2
+:PROPERTIES:
+:EFFORT: 1h
+:END:
+,*** Leaf 3
+:PROPERTIES:
+:EFFORT: 1h
+:END:
+,** Intermediate 2
+:PROPERTIES:
+:EFFORT: 5h
+:END:
+#+end_example
*** Using column view
:PROPERTIES:
