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)
next prev parent 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).