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: Re: Summation of effort estimates in columnview dblock
Date: Sat, 17 Aug 2024 18:39:54 +0200 [thread overview]
Message-ID: <b434baf78d0d4875631913ec8cda245c@condition-alpha.com> (raw)
In-Reply-To: <8734nc30dq.fsf@localhost>
[-- Attachment #1: Type: text/plain, Size: 225 bytes --]
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.
[-- 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: 4274 bytes --]
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)
next prev parent reply other threads:[~2024-08-17 16:40 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. [this message]
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 ` [PATCH] " Alexander Adolf via General discussions about Org-mode.
2024-08-25 13:02 ` 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=b434baf78d0d4875631913ec8cda245c@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).