Ihor Radchenko <[email protected]> writes: > It does not. Looks like you attached an older (?) version of the patch > that uses org-checkbox-direct-children-statistics.
You are right -- I accidentally attached an older version of the patch. Thank you for pointing this out. The corrected patch uses `org-checkbox-children-only-statistics'. >> - `org-hierarchical-todo-statistics' to >> `org-todo-children-only-statistics' > > Same. The corrected patch uses `org-todo-children-only-statistics'. > You also added a branch new test. Why? The additional TODO statistics test covered behavior unrelated to the rename and was therefore outside the scope of this patch. I have removed it. > It is a good idea to link to this thread. Otherwise, the rename > sounds arbitrary. Good catch. I have added a link to this discussion to the commit message. > I generally prefer keeping the obsolete variable names in the index. > This way, people can still find them in the manual and see the new > name. I agree. The corrected patch keeps the obsolete variable names in the manual index alongside the new names. > I think we should bump :package-version after the rename. I have added `:package-version' for both renamed options. Attached is the corrected patch. The existing tests now use the new names and verify that the obsolete aliases resolve to the new variables. Thank you, -- Slawomir Grochowski
>From 7721e0196c2ee085442cc42059fb3f196bd1b2f3 Mon Sep 17 00:00:00 2001 From: Slawomir Grochowski <[email protected]> Date: Tue, 28 Jul 2026 20:50:04 +0200 Subject: [PATCH] org: Rename statistics scope options * lisp/org-list.el (org-checkbox-children-only-statistics): Rename from `org-checkbox-hierarchical-statistics'. Update uses and bump the package version. * lisp/org.el (org-todo-children-only-statistics): Rename from `org-hierarchical-todo-statistics' and bump the package version. (org-update-parent-todo-statistics): Use the new name. * lisp/org-compat.el (org-checkbox-hierarchical-statistics) (org-hierarchical-todo-statistics): Define obsolete aliases. * testing/lisp/test-org-list.el (test-org-list/update-checkbox-count): Test the obsolete alias and use the new checkbox option. * testing/lisp/test-org.el (test-org/update-todo-statistics-cookies): Test the obsolete alias. * doc/org-manual.org: Document the new option names and index the obsolete names. * etc/ORG-NEWS: Announce the renames. Link: https://list.orgmode.org/[email protected]/ Refactoring: Rename Variable. No behavior change. --- doc/org-manual.org | 18 ++++++++++-------- etc/ORG-NEWS | 9 +++++++++ lisp/org-compat.el | 4 ++++ lisp/org-list.el | 5 +++-- lisp/org.el | 9 +++++---- testing/lisp/test-org-list.el | 25 ++++++++++++++++--------- testing/lisp/test-org.el | 3 +++ 7 files changed, 50 insertions(+), 23 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index cd8903a7e..4b91dace8 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -4712,11 +4712,12 @@ meaning of the statistics cookie becomes ambiguous. Set the property =COOKIE_DATA= to either =checkbox= or =todo= to resolve this issue. #+vindex: org-hierarchical-todo-statistics +#+vindex: org-todo-children-only-statistics If you would like to have the statistics cookie count any TODO entries -in the subtree (not just direct children), configure the variable -~org-hierarchical-todo-statistics~. To do this for a single subtree, -include the word =recursive= into the value of the =COOKIE_DATA= -property. +in the subtree (not just direct children), set +~org-todo-children-only-statistics~ to nil. To do this for a single +subtree, include the word =recursive= into the value of the +=COOKIE_DATA= property. #+begin_example ,* Parent capturing statistics [2/20] @@ -4771,6 +4772,7 @@ Here is an example of a checkbox list. #+cindex: checkbox statistics #+cindex: @samp{COOKIE_DATA}, property #+vindex: org-checkbox-hierarchical-statistics +#+vindex: org-checkbox-children-only-statistics The =[2/4]= and =[1/3]= in the first and second line are cookies indicating how many of the checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an @@ -4778,10 +4780,10 @@ idea of how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the headline/item on which the cookie -appears[fn:: Set the variable ~org-checkbox-hierarchical-statistics~ -if you want such cookies to count all checkboxes below the cookie, not -just those belonging to direct children.]. You have to insert the -cookie yourself by typing either =[/]= or =[%]=. With =[/]= you get +appears[fn:: Set the variable ~org-checkbox-children-only-statistics~ +to nil if you want such cookies to count all checkboxes below the +cookie, not just those belonging to direct children.]. You have to +insert the cookie yourself by typing either =[/]= or =[%]=. With =[/]= you get an =n out of m= result, as in the examples above. With =[%]= you get information about the percentage of checkboxes checked (in the above example, this would be =[50%]= and =[33%]=, respectively). In a diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index bb965c02a..01b62b4c9 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -262,6 +262,15 @@ cookie =[N%]=. ** Removed or renamed functions and variables +*** Statistics scope options have been renamed + +~org-checkbox-hierarchical-statistics~ is renamed to +~org-checkbox-children-only-statistics~, and +~org-hierarchical-todo-statistics~ is renamed to +~org-todo-children-only-statistics~. The new names describe the +non-nil behavior explicitly. The old names remain available as +obsolete variable aliases. + *** ~org-babel-remote-temporary-directory~ is now obsolete Org babel now allows TRAMP to determine the best temporary directory. diff --git a/lisp/org-compat.el b/lisp/org-compat.el index 55a4e481e..75e772a17 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -552,6 +552,10 @@ Counting starts at 1." (define-obsolete-function-alias 'org-string-match-p 'string-match-p "9.0") ;;;; Functions and variables from previous releases now obsolete. +(define-obsolete-variable-alias 'org-checkbox-hierarchical-statistics + 'org-checkbox-children-only-statistics "Org 10.0") +(define-obsolete-variable-alias 'org-hierarchical-todo-statistics + 'org-todo-children-only-statistics "Org 10.0") (define-obsolete-variable-alias 'org-edit-src-content-indentation 'org-src-content-indentation "Org 9.8") (define-obsolete-variable-alias 'org-export-ignored-local-variables diff --git a/lisp/org-list.el b/lisp/org-list.el index 8df83663c..8605c6f08 100644 --- a/lisp/org-list.el +++ b/lisp/org-list.el @@ -335,12 +335,13 @@ This hook runs even if checkbox rule in implement alternative ways of collecting statistics information.") -(defcustom org-checkbox-hierarchical-statistics t +(defcustom org-checkbox-children-only-statistics t "Non-nil means checkbox statistics counts only the state of direct children. When nil, all boxes below the cookie are counted. This can be set to nil on a per-node basis using a COOKIE_DATA property with the word \"recursive\" in the value." :group 'org-plain-lists + :package-version '(Org . "10.0") :type 'boolean) (defcustom org-list-indent-offset 0 @@ -2593,7 +2594,7 @@ portion of the buffer." (save-match-data (org-element-context)))) (cookie-data (save-match-data (or (org-entry-get nil "COOKIE_DATA") ""))) (recursivep - (or (not org-checkbox-hierarchical-statistics) + (or (not org-checkbox-children-only-statistics) (string-match-p "\\<recursive\\>" cookie-data)))) (when (and (org-element-type-p context 'statistics-cookie) (not (string-match-p "\\<todo\\>" cookie-data))) diff --git a/lisp/org.el b/lisp/org.el index 294a5eb52..c2d15b3a3 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -2082,13 +2082,14 @@ current entry each time a todo state is changed." (repeat (string :tag "DONE keyword"))) (other :tag "No TODO statistics" nil))) -(defcustom org-hierarchical-todo-statistics t +(defcustom org-todo-children-only-statistics t "Non-nil means TODO statistics covers just direct children. When nil, all entries in the subtree are considered. This has only an effect if `org-provide-todo-statistics' is set. To set this to nil for only a single subtree, use a COOKIE_DATA property and include the word \"recursive\" into the value." :group 'org-todo + :package-version '(Org . "10.0") :type 'boolean) (defcustom org-after-todo-state-change-hook nil @@ -10117,13 +10118,13 @@ respect narrowing." (defvar org-entry-property-inherited-from) ;; defined below (defun org-update-parent-todo-statistics () "Update any statistics cookie in the parent of the current headline. -When `org-hierarchical-todo-statistics' is nil, statistics will cover +When `org-todo-children-only-statistics' is nil, statistics will cover the entire subtree and this will travel up the hierarchy and update statistics everywhere." (let* ((prop (save-excursion (org-up-heading-safe) (org-entry-get nil "COOKIE_DATA" 'inherit))) - (recursive (or (not org-hierarchical-todo-statistics) + (recursive (or (not org-todo-children-only-statistics) (and prop (string-match "\\<recursive\\>" prop)))) (lim (or (and prop (marker-position org-entry-property-inherited-from)) 0)) @@ -10138,7 +10139,7 @@ statistics everywhere." (setq ltoggle (funcall outline-level)) ;; Three situations are to consider: - ;; 1. if `org-hierarchical-todo-statistics' is nil, repeat up + ;; 1. if `org-todo-children-only-statistics' is nil, repeat up ;; to the top-level ancestor on the headline; ;; 2. If parent has "recursive" property, repeat up to the diff --git a/testing/lisp/test-org-list.el b/testing/lisp/test-org-list.el index 1da621143..ecc108c58 100644 --- a/testing/lisp/test-org-list.el +++ b/testing/lisp/test-org-list.el @@ -1129,6 +1129,9 @@ b. Item 2<point>" (ert-deftest test-org-list/update-checkbox-count () "Test `org-update-checkbox-count' specifications." + (should + (eq (indirect-variable 'org-checkbox-hierarchical-statistics) + 'org-checkbox-children-only-statistics)) ;; From a headline. (should (string-match "\\[0/1\\]" @@ -1167,15 +1170,19 @@ b. Item 2<point>" (org-test-with-temp-text "- [ ] item 1\n- [ ] item 2 [/]\n - [X] sub 1" (org-update-checkbox-count) (buffer-string)))) - ;; Count do not apply to sub-lists unless count is not hierarchical. - ;; This state can be achieved with COOKIE_DATA node property set to - ;; "recursive". + ;; Set `org-checkbox-children-only-statistics' to nil to count + ;; checkboxes recursively in sub-lists. Setting the COOKIE_DATA property + ;; to "recursive" enables recursive collection for an individual entry. (should - (string-match "\\[1/1\\]" - (org-test-with-temp-text "- [/]\n - item\n - [X] sub-item" - (let ((org-checkbox-hierarchical-statistics nil)) - (org-update-checkbox-count)) - (buffer-string)))) + (string-prefix-p + "- [1/1]" + (org-test-with-temp-text + (concat "- [/]\n" + " - item\n" + " - [X] sub-item") + (let ((org-checkbox-children-only-statistics nil)) + (org-update-checkbox-count)) + (buffer-string)))) (should (string-match "\\[1/1\\]" (org-test-with-temp-text " @@ -1210,7 +1217,7 @@ b. Item 2<point>" - [X] item :END: - [X] item2" - (let ((org-checkbox-hierarchical-statistics nil)) + (let ((org-checkbox-children-only-statistics nil)) (org-update-checkbox-count)) (buffer-string)))) (let ((checklist (concat "- [%]\n" ; 0/101 = 0% diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el index 9e9be9ebc..cb9ecf6ee 100644 --- a/testing/lisp/test-org.el +++ b/testing/lisp/test-org.el @@ -4315,6 +4315,9 @@ text" (ert-deftest test-org/update-todo-statistics-cookies () "Test updating TODO statistics cookies." + (should + (eq (indirect-variable 'org-hierarchical-todo-statistics) + 'org-todo-children-only-statistics)) (let ((N 3) (parent "* [/]")) (dolist (n (number-sequence 0 N)) -- 2.39.5
