[PATCH] doc/org-manual.org (Checkboxes): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

["Sławomir Grochowski" <slawomir.grochowski@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 569 bytes --]

Dear All,

Dear All,

I propose to move the section "Checkboxes".
From "5 TODO Items -> 5.6 Checkboxes"
To: "2 Document Structure -> 2.6 Plain Lists -> 2.6.1 Checkboxes"

Because checkbox can only exist in a plain list, as a plain list feature.
So the section should be under 'Plain Lists' heading not under 'TODO Items'.

Link https://orgmode.org/org.html#Checkboxes would stay the same.
So it's just a move section to a more suitable place.
Without changing the content.

What do you think?
Patch in the attachment.

Regards,
Sławomir Grochowski

[-- Attachment #1.2: Type: text/html, Size: 788 bytes --]

[-- Attachment #2: 0001-doc-org-manual.org-Checkboxes-move-section-to-Plain-.patch --]
[-- Type: text/x-patch, Size: 14617 bytes --]

From ff2c4be8188a5faed6dfb91b2315e58573f91fa8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C5=82awomir=20Grochowski?= <slawomir.grochowski@gmail.com>
Date: Thu, 25 Jan 2024 10:03:09 +0100
Subject: [PATCH] doc/org-manual.org (Checkboxes): move section to 'Plain
 Lists'

* doc/org-manual.org (Checkboxes): move section 'Checkboxes' from
'TODO Items' to 'Plain Lists'.  Because checkbox can only exist in a
plain list, as a plain list feature.  So section should be under
'Plain Lists' heading not under 'TODO Items'.
---
 doc/org-manual.org | 330 ++++++++++++++++++++++-----------------------
 1 file changed, 165 insertions(+), 165 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index d8c7fd737..71e72ddd8 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -1308,6 +1308,171 @@ to disable them individually.
   Sort the plain list.  Prompt for the sorting method: numerically,
   alphabetically, by time, or by custom function.
 
+*** Checkboxes
+:PROPERTIES:
+:DESCRIPTION: Tick-off lists.
+:END:
+#+cindex: checkboxes
+
+#+vindex: org-list-automatic-rules
+Every item in a plain list[fn:17] (see [[*Plain Lists]]) can be made into
+a checkbox by starting it with the string =[ ]=.  This feature is
+similar to TODO items (see [[*TODO Items]]), but is more lightweight.
+Checkboxes are not included into the global TODO list, so they are
+often great to split a task into a number of simple steps.  Or you can
+use them in a shopping list.
+
+Here is an example of a checkbox list.
+
+#+begin_example
+,* TODO Organize party [2/4]
+  - [-] call people [1/3]
+    - [ ] Peter
+    - [X] Sarah
+    - [ ] Sam
+  - [X] order food
+  - [ ] think about what music to play
+  - [X] talk to the neighbors
+#+end_example
+
+A checkbox can be in one of the three states:
+1. not checked =[ ]=
+2. partially checked =[-]=
+3. checked =[X]=
+
+Checkboxes work hierarchically, so if a checkbox item has children
+that are checkboxes, toggling one of the children checkboxes makes the
+parent checkbox reflect if none, some, or all of the children are
+checked.
+
+If all child checkboxes are not checked, the parent checkbox is also not checked.
+#+begin_example
+- [ ] call people
+  - [ ] Peter
+  - [ ] Sarah
+#+end_example
+
+If some but not all child checkboxes are checked, the parent checkbox is partially checked.
+#+begin_example
+- [-] call people
+  - [X] Peter
+  - [ ] Sarah
+#+end_example
+
+If all child checkboxes are checked, the parent checkbox is also checked.
+#+begin_example
+- [X] call people
+  - [X] Peter
+  - [X] Sarah
+#+end_example
+
+#+cindex: statistics, for checkboxes
+#+cindex: checkbox statistics
+#+cindex: @samp{COOKIE_DATA}, property
+#+vindex: org-checkbox-hierarchical-statistics
+The =[2/4]= and =[1/3]= in the first and second line are cookies
+indicating how many checkboxes present in this entry have been checked
+off, and the total number of checkboxes present.  This can give you an
+idea on 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
+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
+headline, a cookie can count either checkboxes below the heading or
+TODO states of children, and it displays whatever was changed last.
+Set the property =COOKIE_DATA= to either =checkbox= or =todo= to
+resolve this issue.
+
+#+cindex: blocking, of checkboxes
+#+cindex: checkbox blocking
+#+cindex: @samp{ORDERED}, property
+If the current outline node has an =ORDERED= property, checkboxes must
+be checked off in sequence, and an error is thrown if you try to check
+off a box while there are unchecked boxes above it.
+
+The following commands work with checkboxes:
+
+- {{{kbd(C-c C-c)}}} (~org-toggle-checkbox~) ::
+
+  #+kindex: C-c C-c
+  #+findex: org-toggle-checkbox
+  Toggle checkbox status or---with prefix argument---checkbox presence
+  at point.  With a single prefix argument, add an empty checkbox or
+  remove the current one[fn:: {{{kbd(C-u C-c C-c)}}} on the /first/
+  item of a list with no checkbox adds checkboxes to the rest of the
+  list.].  With a double prefix argument, set it to =[-]=, which is
+  considered to be an intermediate state.
+
+- {{{kbd(C-c C-x C-b)}}} (~org-toggle-checkbox~) ::
+
+  #+kindex: C-c C-x C-b
+  Toggle checkbox status or---with prefix argument---checkbox presence
+  at point.  With double prefix argument, set it to =[-]=, which is
+  considered to be an intermediate state.
+
+  - If there is an active region, toggle the first checkbox in the
+    region and set all remaining boxes to the same status as the
+    first.  With a prefix argument, add or remove the checkbox for all
+    items in the region.
+
+  - If point is in a headline, toggle checkboxes in the region between
+    this headline and the next---so /not/ the entire subtree.
+
+  - If there is no active region, just toggle the checkbox at point.
+
+- {{{kbd(C-c C-x C-r)}}} (~org-toggle-radio-button~) ::
+
+  #+kindex: C-c C-x C-r
+  #+findex: org-toggle-radio-button
+  #+cindex: radio button, checkbox as
+  Toggle checkbox status by using the checkbox of the item at point as
+  a radio button: when the checkbox is turned on, all other checkboxes
+  on the same level will be turned off.  With a universal prefix
+  argument, toggle the presence of the checkbox.  With a double prefix
+  argument, set it to =[-]=.
+
+  #+findex: org-list-checkbox-radio-mode
+  {{{kbd(C-c C-c)}}} can be told to consider checkboxes as radio buttons by
+  setting =#+ATTR_ORG: :radio t= right before the list or by calling
+  {{{kbd(M-x org-list-checkbox-radio-mode)}}} to activate this minor mode.
+
+- {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) ::
+
+  #+kindex: M-S-RET
+  #+findex: org-insert-todo-heading
+  Insert a new item with a checkbox.  This works only if point is
+  already in a plain list item (see [[*Plain Lists]]).
+
+- {{{kbd(C-c C-x o)}}} (~org-toggle-ordered-property~) ::
+
+  #+kindex: C-c C-x o
+  #+findex: org-toggle-ordered-property
+  #+vindex: org-track-ordered-property-with-tag
+  Toggle the =ORDERED= property of the entry, to toggle if checkboxes
+  must be checked off in sequence.  A property is used for this
+  behavior because this should be local to the current entry, not
+  inherited like a tag.  However, if you would like to /track/ the
+  value of this property with a tag for better visibility, customize
+  ~org-track-ordered-property-with-tag~.
+
+- {{{kbd(C-c #)}}} (~org-update-statistics-cookies~) ::
+
+  #+kindex: C-c #
+  #+findex: org-update-statistics-cookies
+  Update the statistics cookie in the current outline entry.  When
+  called with a {{{kbd(C-u)}}} prefix, update the entire file.
+  Checkbox statistic cookies are updated automatically if you toggle
+  checkboxes with {{{kbd(C-c C-c)}}} and make new ones with
+  {{{kbd(M-S-RET)}}}.  TODO statistics cookies update when changing
+  TODO states.  If you delete boxes/entries or add/change them by
+  hand, use this command to get things back into sync.
+
 ** Drawers
 :PROPERTIES:
 :DESCRIPTION: Tucking stuff away.
@@ -4658,171 +4823,6 @@ all children are done, you can use the following setup:
 Another possibility is the use of checkboxes to identify (a hierarchy
 of) a large number of subtasks (see [[*Checkboxes]]).
 
-** Checkboxes
-:PROPERTIES:
-:DESCRIPTION: Tick-off lists.
-:END:
-#+cindex: checkboxes
-
-#+vindex: org-list-automatic-rules
-Every item in a plain list[fn:17] (see [[*Plain Lists]]) can be made into
-a checkbox by starting it with the string =[ ]=.  This feature is
-similar to TODO items (see [[*TODO Items]]), but is more lightweight.
-Checkboxes are not included into the global TODO list, so they are
-often great to split a task into a number of simple steps.  Or you can
-use them in a shopping list.
-
-Here is an example of a checkbox list.
-
-#+begin_example
-,* TODO Organize party [2/4]
-  - [-] call people [1/3]
-    - [ ] Peter
-    - [X] Sarah
-    - [ ] Sam
-  - [X] order food
-  - [ ] think about what music to play
-  - [X] talk to the neighbors
-#+end_example
-
-A checkbox can be in one of the three states:
-1. not checked =[ ]=
-2. partially checked =[-]=
-3. checked =[X]=
-
-Checkboxes work hierarchically, so if a checkbox item has children
-that are checkboxes, toggling one of the children checkboxes makes the
-parent checkbox reflect if none, some, or all of the children are
-checked.
-
-If all child checkboxes are not checked, the parent checkbox is also not checked.
-#+begin_example
-- [ ] call people
-  - [ ] Peter
-  - [ ] Sarah
-#+end_example
-
-If some but not all child checkboxes are checked, the parent checkbox is partially checked.
-#+begin_example
-- [-] call people
-  - [X] Peter
-  - [ ] Sarah
-#+end_example
-
-If all child checkboxes are checked, the parent checkbox is also checked.
-#+begin_example
-- [X] call people
-  - [X] Peter
-  - [X] Sarah
-#+end_example
-
-#+cindex: statistics, for checkboxes
-#+cindex: checkbox statistics
-#+cindex: @samp{COOKIE_DATA}, property
-#+vindex: org-checkbox-hierarchical-statistics
-The =[2/4]= and =[1/3]= in the first and second line are cookies
-indicating how many checkboxes present in this entry have been checked
-off, and the total number of checkboxes present.  This can give you an
-idea on 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
-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
-headline, a cookie can count either checkboxes below the heading or
-TODO states of children, and it displays whatever was changed last.
-Set the property =COOKIE_DATA= to either =checkbox= or =todo= to
-resolve this issue.
-
-#+cindex: blocking, of checkboxes
-#+cindex: checkbox blocking
-#+cindex: @samp{ORDERED}, property
-If the current outline node has an =ORDERED= property, checkboxes must
-be checked off in sequence, and an error is thrown if you try to check
-off a box while there are unchecked boxes above it.
-
-The following commands work with checkboxes:
-
-- {{{kbd(C-c C-c)}}} (~org-toggle-checkbox~) ::
-
-  #+kindex: C-c C-c
-  #+findex: org-toggle-checkbox
-  Toggle checkbox status or---with prefix argument---checkbox presence
-  at point.  With a single prefix argument, add an empty checkbox or
-  remove the current one[fn:: {{{kbd(C-u C-c C-c)}}} on the /first/
-  item of a list with no checkbox adds checkboxes to the rest of the
-  list.].  With a double prefix argument, set it to =[-]=, which is
-  considered to be an intermediate state.
-
-- {{{kbd(C-c C-x C-b)}}} (~org-toggle-checkbox~) ::
-
-  #+kindex: C-c C-x C-b
-  Toggle checkbox status or---with prefix argument---checkbox presence
-  at point.  With double prefix argument, set it to =[-]=, which is
-  considered to be an intermediate state.
-
-  - If there is an active region, toggle the first checkbox in the
-    region and set all remaining boxes to the same status as the
-    first.  With a prefix argument, add or remove the checkbox for all
-    items in the region.
-
-  - If point is in a headline, toggle checkboxes in the region between
-    this headline and the next---so /not/ the entire subtree.
-
-  - If there is no active region, just toggle the checkbox at point.
-
-- {{{kbd(C-c C-x C-r)}}} (~org-toggle-radio-button~) ::
-
-  #+kindex: C-c C-x C-r
-  #+findex: org-toggle-radio-button
-  #+cindex: radio button, checkbox as
-  Toggle checkbox status by using the checkbox of the item at point as
-  a radio button: when the checkbox is turned on, all other checkboxes
-  on the same level will be turned off.  With a universal prefix
-  argument, toggle the presence of the checkbox.  With a double prefix
-  argument, set it to =[-]=.
-
-  #+findex: org-list-checkbox-radio-mode
-  {{{kbd(C-c C-c)}}} can be told to consider checkboxes as radio buttons by
-  setting =#+ATTR_ORG: :radio t= right before the list or by calling
-  {{{kbd(M-x org-list-checkbox-radio-mode)}}} to activate this minor mode.
-
-- {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) ::
-
-  #+kindex: M-S-RET
-  #+findex: org-insert-todo-heading
-  Insert a new item with a checkbox.  This works only if point is
-  already in a plain list item (see [[*Plain Lists]]).
-
-- {{{kbd(C-c C-x o)}}} (~org-toggle-ordered-property~) ::
-
-  #+kindex: C-c C-x o
-  #+findex: org-toggle-ordered-property
-  #+vindex: org-track-ordered-property-with-tag
-  Toggle the =ORDERED= property of the entry, to toggle if checkboxes
-  must be checked off in sequence.  A property is used for this
-  behavior because this should be local to the current entry, not
-  inherited like a tag.  However, if you would like to /track/ the
-  value of this property with a tag for better visibility, customize
-  ~org-track-ordered-property-with-tag~.
-
-- {{{kbd(C-c #)}}} (~org-update-statistics-cookies~) ::
-
-  #+kindex: C-c #
-  #+findex: org-update-statistics-cookies
-  Update the statistics cookie in the current outline entry.  When
-  called with a {{{kbd(C-u)}}} prefix, update the entire file.
-  Checkbox statistic cookies are updated automatically if you toggle
-  checkboxes with {{{kbd(C-c C-c)}}} and make new ones with
-  {{{kbd(M-S-RET)}}}.  TODO statistics cookies update when changing
-  TODO states.  If you delete boxes/entries or add/change them by
-  hand, use this command to get things back into sync.
-
 * Tags
 :PROPERTIES:
 :DESCRIPTION: Tagging headlines and matching sets of tags.
-- 
2.30.2