Improve documentation about hierarchical versus recursive statistics

doc/org.texi

@@ -3803,6 +3803,7 @@ priority):
 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
 @section Breaking tasks down into subtasks
 @cindex tasks, breaking down
+@cindex statistics, for TODO items
 
 @vindex org-agenda-todo-list-sublevels
 It is often advisable to break down large tasks into smaller, manageable
@@ -3828,6 +3829,19 @@ the statistics cookie become ambiguous.  Set the property
 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
 this issue.
 
+If you would like to have the statistics cookie count any TODO entries in the
+subtree (not just direct children), confgure the variable
+@code{org-hierarchical-todo-statistics}.  To do this for a single subtree,
+include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
+property.
+
+@example
+* Parent capturing statistics [2/20]
+  :PROPERTIES:
+  :COOKIE_DATA: todo recursive
+  :END:
+@end example
+
 If you would like a TODO entry to automatically change to DONE
 when all children are done, you can use the following setup:
 
@@ -3885,7 +3899,7 @@ 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@footnote{Set the variable
-@code{org-recursive-checkbox-statistics} if you want such cookies to
+@code{org-hierarchical-checkbox-statistics} if you want such cookies to
 represent the all checkboxes below the cookie, not just the direct
 children.}.  You have to insert the cookie yourself by typing either
 @samp{[/]} or @samp{[%]}.  With @samp{[/]} you get an @samp{n out of m}

lisp/ChangeLog

@@ -1,5 +1,10 @@
 2009-08-18  Carsten Dominik  <carsten.dominik@gmail.com>
 
+	* org.el (org-hierarchical-todo-statistics): Improve docstring.
+
+	* org-list.el (org-hierarchical-checkbox-statistics): Improve
+	docstring.
+
 	* org.el (org-emphasis-regexp-components): Add "`" to set of
 	pre-emphasis characters.
 

lisp/org-list.el

@@ -149,7 +149,9 @@ toggle a checkbox with \\[org-ctrl-c-ctrl-c]."
 
 (defcustom org-hierarchical-checkbox-statistics t
   "Non-nil means, checkbox statistics counts only the state of direct children.
-When nil, all boxes below the cookie are counted."
+When nil, all boxes below the cookie are counted.
+This can be set to nil on a per-node basis using a COCKIE_DATA property
+with the word \"recursive\" in the value."
   :group 'org-plain-lists
   :type 'boolean)
 

lisp/org.el

@@ -1752,7 +1752,9 @@ current entry each time a todo state is changed."
 (defcustom org-hierarchical-todo-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."
+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
   :type 'boolean)