emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Alexander Adolf via "General discussions about Org-mode." <emacs-orgmode@gnu.org>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode@gnu.org,
	"Sławomir Grochowski" <slawomir.grochowski@gmail.com>
Subject: [PATCH] Re: Summation of effort estimates in columnview dblock
Date: Fri, 23 Aug 2024 15:32:53 +0200	[thread overview]
Message-ID: <b46539132be3ed81d1b6da24dac4a1b8@condition-alpha.com> (raw)
In-Reply-To: <f2cdf50bf412972a7b5d6f3f1b733217@condition-alpha.com>

[-- Attachment #1: Type: text/plain, Size: 90 bytes --]

Ping?

(NOTE: Updated documentation patch below has one very minor typo fixed. END NOTE)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-better-explain-columnview-column-.patch --]
[-- Type: text/x-patch, Size: 8093 bytes --]

From 1a862dd5af174af480cedf35fbed94a7e4dfb69b 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 | 211 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 207 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebca..18fc9a4fa 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,211 @@ 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's 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.
+
+The following example illustrates how special, and non-special
+properties contribute to the summary results, and how the property
+values of the headlines get updated.  Consider the following buffer
+contents (the =#+BEGIN= must be on a single line, and is wrapped here
+for readability only):
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+When the colmnview dynamic block is now updated by {{{kbd(C-c C-c)}}}
+or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) with the cursor
+somewhere on the =#+BEGIN= line, the buffer contents shown below will
+result.  Note how the values of the =EFFORT= property of =Task 1= and
+=Task 1.1= were updated to eleven days, and to seven days
+respectively.  Note also, how the =CLOCKSUM= of thirteen days for
+=Task 1= includes the two days which were clocked on the headline
+itself.  Comparing the two estimated, and the two clocksum columns
+with each other in the table shows how the first summary type
+specification determines the summary calculation for a given property.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+| Task             | Estimated Total | Estimated | Clocked Total | Clocked  |
+|------------------+-----------------+-----------+---------------+----------|
+| Task 1           |        11d 0:00 |  11d 0:00 | 13d 0:00      | 13d 0:00 |
+| \_  Task 1.1     |         7d 0:00 |   7d 0:00 | 7d 0:00       | 7d 0:00  |
+| \_    Task 1.1.1 |              3d |        3d | 3d 0:00       | 3d 0:00  |
+| \_    Task 1.1.2 |              4d |        4d | 4d 0:00       | 4d 0:00  |
+| \_  Task 1.2     |              4d |        4d | 4d 0:00       | 4d 0:00  |
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   11d 0:00
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   7d 0:00
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+        CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+Starting again from the same initial example buffer content, but with
+a modified =#+BEGIN= line that swaps the order of the two estimated,
+and the two clocksum columns, the result of updating the columnview
+dynamic block will be as shown below.  Note the different results in
+the estimated column without a summary type.  Also note that the
+=EFFORT= properties of the =Task 1= and =Task 1.1= headlines were not
+updated in this case, because the first column specification for the
+=EFFORT= property has no summary type.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated) %EFFORT(Estimated Total){:} \
+          %CLOCKSUM(Clocked) %CLOCKSUM(Clocked Total){:}" :id global
+| Task             | Estimated | Estimated Total | Clocked  | Clocked Total |
+|------------------+-----------+-----------------+----------+---------------|
+| Task 1           |        2d |        11d 0:00 | 13d 0:00 | 13d 0:00      |
+| \_  Task 1.1     |        2d |         7d 0:00 | 7d 0:00  | 7d 0:00       |
+| \_    Task 1.1.1 |        3d |              3d | 3d 0:00  | 3d 0:00       |
+| \_    Task 1.1.2 |        4d |              4d | 4d 0:00  | 4d 0:00       |
+| \_  Task 1.2     |        4d |              4d | 4d 0:00  | 4d 0:00       |
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
 *** Using column view
 :PROPERTIES:
 :DESCRIPTION: How to create and use column view.
-- 
2.39.3 (Apple Git-146)


  reply	other threads:[~2024-08-23 13:33 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-08-07 16:24 Summation of effort estimates in columnview dblock Alexander Adolf via General discussions about Org-mode.
2024-08-07 19:48 ` Ihor Radchenko
2024-08-08 17:43   ` Alexander Adolf via General discussions about Org-mode.
2024-08-10 14:42     ` Ihor Radchenko
2024-08-16 20:10       ` Alexander Adolf via General discussions about Org-mode.
2024-08-18 12:08         ` Ihor Radchenko
2024-08-17 16:39       ` Alexander Adolf via General discussions about Org-mode.
2024-08-18 12:23         ` Ihor Radchenko
2024-08-20 13:06           ` Alexander Adolf via General discussions about Org-mode.
2024-08-23 13:32             ` Alexander Adolf via General discussions about Org-mode. [this message]
2024-08-25 13:02               ` [PATCH] " Ihor Radchenko
2024-08-26 16:44                 ` Alexander Adolf via General discussions about Org-mode.
2024-08-30 15:42                 ` Alexander Adolf via General discussions about Org-mode.

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=b46539132be3ed81d1b6da24dac4a1b8@condition-alpha.com \
    --to=emacs-orgmode@gnu.org \
    --cc=alexander.adolf@condition-alpha.com \
    --cc=slawomir.grochowski@gmail.com \
    --cc=yantar92@posteo.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).