Re: Summation of effort estimates in columnview dblock

[Alexander Adolf]

Ihor Radchenko <yantar92@posteo.net> writes:

> [...]
> I agree that the manual can be improved. It would be nice if someone
> actively using column views contributed such an improvement ;)
> [...]

Ok, I've given it a try.

>From 4bb89a24269ee2ef42ed2b1c5713faa37b33f72d Mon Sep 17 00:00:00 2001
From: Alexander Adolf <alexander.adolf@condition-alpha.com>
Date: Sat, 17 Aug 2024 18:29:51 +0200
Subject: [PATCH] doc/org-manual.org: better explain columnview column summary
 types

* doc/org-manual.org (Column attributes): Shed more words on how
summary types for columnview columns work, which property values are
taken into account, and which property values get updated in the
buffer under what circumstances.
---
 doc/org-manual.org | 39 +++++++++++++++++++++++++++++++++++----
 etc/ORG-NEWS       |  6 ++++++
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebca..b435a4526 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5734,10 +5734,8 @@ 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 and property values for
+  ancestor nodes are computed from their descendants.
 
   Supported summary types are:
 
@@ -5810,6 +5808,39 @@ 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.
 
+When using summary types for non-special properties like the
+=Time_Estimate= column in the example, the collection of data for the
+summary in each subtree within scope will start at the furthest
+descendant nodes which have the respective property.  When any of
+their sibling nodes also have the property in question, all the
+siblings' values of the property are used to compute the summary
+result according to the summary type specified.  Then the closest
+ancestor node which also has the respective property is located, and
+the buffer is modified as the value of that node's property is updated
+with the summary result of its descendant nodes.  This process is
+repeated starting from each updated node, until the top of each
+subtree has been reached, and all branches of the subtree have been
+traversed.  Since the property values of ancestor nodes get updated in
+this process, only the furthest descendant nodes which have the
+respective property along each subtree axis will contribute to the
+summary results.
+
+When a non-special property appears more than once in a columns
+definition, and with different summary type specifications (including
+with none), the values of that property present on any ancestor nodes
+will be updated according to the summary type specification (if any)
+of the first instance of the property in the columns definition.
+Hence, when the first occurrence of a property in a columns definition
+has no summary type specification, the property values of ancestor
+nodes will not be updated.
+
+When using summary types with columns for the special properties
+=CLOCKSUM= and =CLOCKSUM_T=, the summary process will be different.
+First, as these are special properties that are not stored in property
+drawers, no updates will be made to any nodes involved.  Secondly, the
+summary value will be computed not just from the furthest descendant
+nodes, but from the special property values of all nodes in a subtree.
+
 *** Using column view
 :PROPERTIES:
 :DESCRIPTION: How to create and use column view.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 6f858f3ca..3e81f0f46 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -187,6 +187,12 @@ This way, attachments will remain accessible when opening 
symlinked Org file.
 When no attach dir exists, Org mode will still prefer creating it in
 the "default" directory - where the symlink is located.
 
+*** improved description of how summary types in column definitions for 
columnview work
+
+Made the manual more explicit about how summary types work for
+non-special and special properties, and when which property's value
+gets updated in the buffer when a columnview is updated.
+
 * Version 9.7
 
 ** Important announcements and breaking changes
-- 
2.39.3 (Apple Git-146)