From ff2c4be8188a5faed6dfb91b2315e58573f91fa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C5=82awomir=20Grochowski?= 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