Hi,
I would like to add recursive checkbox collection for column-view
summary cookies to `org-colview.el'. This would require a new user
option controlling whether checkbox values are collected recursively.
Org already provides analogous options for checkbox and TODO
statistics:
- `org-checkbox-hierarchical-statistics'
- `org-hierarchical-todo-statistics'
Before adding the new option, I would like to make the naming of the
existing options consistent and, possibly, clarify their semantics.
A minimal change would be to make the word order consistent. After the
`org-' prefix, an option name would first identify the object to which
it applies (`checkbox' or `todo'), followed by the behavior it controls
(`hierarchical-statistics'). Following this convention, the pair
would be:
- `org-checkbox-hierarchical-statistics'
- `org-todo-hierarchical-statistics'
There is a direct precedent for this change. The checkbox option was
previously named `org-hierarchical-checkbox-statistics', but it was
renamed to `org-checkbox-hierarchical-statistics' in commit f373bca58,
with the old name retained as an obsolete variable alias.
The minimal proposal would therefore be to rename:
`org-hierarchical-todo-statistics'
to `org-todo-hierarchical-statistics'
This would not change any behavior. Since this is a public user
option, the old name would remain available as an obsolete variable
alias for backward compatibility.
However, I wonder whether this would be a good opportunity to make the
names clearer as well. The word "hierarchical" does not indicate
whether statistics cover only direct children or the entire subtree.
The current polarity also makes the behavior harder to infer: non-nil
means considering direct children only, whereas nil enables recursive
collection.
Would it make sense to rename both options to:
- `org-checkbox-recursive-statistics'
- `org-todo-recursive-statistics'
and give them positive semantics? With the proposed names, non-nil
would mean collecting statistics recursively, whereas nil would mean
considering direct children only. The new options would default to
nil, preserving the current default behavior.
In other words, the value migration would be:
org-checkbox-recursive-statistics =
(not org-checkbox-hierarchical-statistics)
and likewise for TODO statistics.
This terminology would also match the `recursive' value already
accepted by the `COOKIE_DATA' property. It would additionally make the
word order consistent between the checkbox and TODO options.
The main complication is backward compatibility: an ordinary obsolete
variable alias would not be sufficient because the polarity of the
value would change.
Would introducing the clearer names be worthwhile? If so, what
migration approach would be preferable? Alternatively, I can limit
the change to the minimal, behavior-preserving rename described above.
Best,
--
Slawomir Grochowski
