* [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples @ 2023-11-06 12:50 Sławomir Grochowski 2023-11-06 16:49 ` Bastien 0 siblings, 1 reply; 11+ messages in thread From: Sławomir Grochowski @ 2023-11-06 12:50 UTC (permalink / raw) To: emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 262 bytes --] Dear All, I have added some examples to the org-manual. Patch in attachment and also a screenshot of generated html. Thank you for the code review. Now please help me find everything that can be improved in this patch. Regards, Sławomir Grochowski [-- Attachment #1.2: Type: text/html, Size: 404 bytes --] [-- Attachment #2: Screenshot from 2023-11-06 13-45-26.png --] [-- Type: image/png, Size: 132052 bytes --] [-- Attachment #3: 0001-doc-org-manual.org-Checkboxes-add-checkbox-states-ex.patch --] [-- Type: text/x-patch, Size: 1619 bytes --] From ef77008df33bcc6b967e6502c40ebcd9b134a7c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C5=82awomir=20Grochowski?= <slawomir.grochowski@gmail.com> Date: Mon, 6 Nov 2023 13:27:06 +0100 Subject: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples * org-manual.org: Checkboxes, add checkbox states examples --- doc/org-manual.org | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/org-manual.org b/doc/org-manual.org index 50662669e..4ab8b7915 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -4602,11 +4602,37 @@ Here is an example of a checkbox list. - [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 -- 2.30.2 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-06 12:50 [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples Sławomir Grochowski @ 2023-11-06 16:49 ` Bastien 2023-11-06 17:05 ` Ihor Radchenko ` (2 more replies) 0 siblings, 3 replies; 11+ messages in thread From: Bastien @ 2023-11-06 16:49 UTC (permalink / raw) To: Sławomir Grochowski; +Cc: emacs-orgmode Hi Sławomir, Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: > I have added some examples to the org-manual. > Patch in attachment and also a screenshot of generated html. Applied, with a minor modification, using 1. instead of 1) for the list items. I added you as a contributor on https://orgmode.org/worg/contributors.html Thanks! -- Bastien ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-06 16:49 ` Bastien @ 2023-11-06 17:05 ` Ihor Radchenko 2023-11-06 17:19 ` Bastien 2023-11-07 17:30 ` Sławomir Grochowski 2024-01-27 20:55 ` Sławomir Grochowski 2 siblings, 1 reply; 11+ messages in thread From: Ihor Radchenko @ 2023-11-06 17:05 UTC (permalink / raw) To: Bastien; +Cc: Sławomir Grochowski, emacs-orgmode Bastien <bzg@gnu.org> writes: > I added you as a contributor on > https://orgmode.org/worg/contributors.html I think that you added him second time :) @@ 260,6 260,7 @@ within GNU Emacs: ... +- Slawomir Grochowski - Sławomir Grochowski ... -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-06 17:05 ` Ihor Radchenko @ 2023-11-06 17:19 ` Bastien 0 siblings, 0 replies; 11+ messages in thread From: Bastien @ 2023-11-06 17:19 UTC (permalink / raw) To: Ihor Radchenko; +Cc: Sławomir Grochowski, emacs-orgmode Ihor Radchenko <yantar92@posteo.net> writes: > Bastien <bzg@gnu.org> writes: > >> I added you as a contributor on >> https://orgmode.org/worg/contributors.html > > I think that you added him second time :) Ahah, good catch! > @@ 260,6 260,7 @@ within GNU Emacs: > ... > +- Slawomir Grochowski > - Sławomir Grochowski I fixed this by keeping the second occurrence with "ł"... -- Bastien ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-06 16:49 ` Bastien 2023-11-06 17:05 ` Ihor Radchenko @ 2023-11-07 17:30 ` Sławomir Grochowski 2023-11-07 23:36 ` Bastien Guerry 2024-01-27 20:55 ` Sławomir Grochowski 2 siblings, 1 reply; 11+ messages in thread From: Sławomir Grochowski @ 2023-11-07 17:30 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 775 bytes --] > Applied, with a minor modification, using 1. instead of 1) for the > list items. When will you merge the patch? https://git.savannah.gnu.org/cgit/emacs/org-mode.git/ And when update will be visible on site https://orgmode.org/org.html#Checkboxes ? Regards, Sławomir Grochowski On Mon, Nov 6, 2023 at 5:49 PM Bastien <bzg@gnu.org> wrote: > Hi Sławomir, > > Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: > > > I have added some examples to the org-manual. > > Patch in attachment and also a screenshot of generated html. > > Applied, with a minor modification, using 1. instead of 1) for the > list items. > > I added you as a contributor on > https://orgmode.org/worg/contributors.html > > Thanks! > > -- > Bastien > [-- Attachment #2: Type: text/html, Size: 1462 bytes --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-07 17:30 ` Sławomir Grochowski @ 2023-11-07 23:36 ` Bastien Guerry 2023-11-08 6:36 ` Sławomir Grochowski 0 siblings, 1 reply; 11+ messages in thread From: Bastien Guerry @ 2023-11-07 23:36 UTC (permalink / raw) To: Sławomir Grochowski; +Cc: emacs-orgmode Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: >> Applied, with a minor modification, using 1. instead of 1) for the >> list items. > > When will you merge the patch? https://git.savannah.gnu.org/cgit/ > emacs/org-mode.git/ Done now. > And when update will be visible on site https://orgmode.org/org.html# > Checkboxes ? When we release the main branch as a new stable version of Org, so not so soon. Best, -- Bastien Guerry ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-07 23:36 ` Bastien Guerry @ 2023-11-08 6:36 ` Sławomir Grochowski 0 siblings, 0 replies; 11+ messages in thread From: Sławomir Grochowski @ 2023-11-08 6:36 UTC (permalink / raw) To: Bastien Guerry; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 704 bytes --] Awesome! Thank you Bastien. I'm planning to add some examples with checkbox cookie data. Regards, Sławomir Grochowski On Wed, Nov 8, 2023 at 12:37 AM Bastien Guerry <bzg@gnu.org> wrote: > Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: > > >> Applied, with a minor modification, using 1. instead of 1) for the > >> list items. > > > > When will you merge the patch? https://git.savannah.gnu.org/cgit/ > > emacs/org-mode.git/ > > Done now. > > > And when update will be visible on site https://orgmode.org/org.html# > > Checkboxes ? > > When we release the main branch as a new stable version of Org, so not > so soon. > > Best, > > -- > Bastien Guerry > [-- Attachment #2: Type: text/html, Size: 1333 bytes --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2023-11-06 16:49 ` Bastien 2023-11-06 17:05 ` Ihor Radchenko 2023-11-07 17:30 ` Sławomir Grochowski @ 2024-01-27 20:55 ` Sławomir Grochowski 2024-01-27 22:01 ` Matt 2024-02-01 15:50 ` Ihor Radchenko 2 siblings, 2 replies; 11+ messages in thread From: Sławomir Grochowski @ 2024-01-27 20:55 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 794 bytes --] Dear All, I noticed in my patch that I moved the description ("The ‘[2/4]’ and ‘[1/3]’ in") of an example. And it should be just below the example. So I'm sending a fixup! patch to fix this. It's my first fixup! patch so I hope this is the right procedure ;) Regards, Sławomir Grochowski On Mon, Nov 6, 2023 at 5:49 PM Bastien <bzg@gnu.org> wrote: > Hi Sławomir, > > Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: > > > I have added some examples to the org-manual. > > Patch in attachment and also a screenshot of generated html. > > Applied, with a minor modification, using 1. instead of 1) for the > list items. > > I added you as a contributor on > https://orgmode.org/worg/contributors.html > > Thanks! > > -- > Bastien > [-- Attachment #1.2: Type: text/html, Size: 1402 bytes --] [-- Attachment #2: 0001-fixup-doc-org-manual.org-Checkboxes-add-checkbox-sta.patch --] [-- Type: text/x-patch, Size: 4497 bytes --] From 01bbdca4a5b8a7445f8b9dceef4481ea7b4c5c75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C5=82awomir=20Grochowski?= <slawomir.grochowski@gmail.com> Date: Sat, 27 Jan 2024 21:16:36 +0100 Subject: [PATCH] fixup! doc/org-manual.org: Checkboxes, add checkbox states examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Description of example of a checkbox list ("The ‘[2/4]’ and ‘[1/3]’...") should be right below the example. --- doc/org-manual.org | 60 +++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index d8c7fd737..2064e1e68 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -4685,6 +4685,36 @@ Here is an example of a checkbox list. - [X] talk to the neighbors #+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. + A checkbox can be in one of the three states: 1. not checked =[ ]= 2. partially checked =[-]= @@ -4716,36 +4746,6 @@ If all child checkboxes are checked, the parent checkbox is also checked. - [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~) :: -- 2.30.2 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2024-01-27 20:55 ` Sławomir Grochowski @ 2024-01-27 22:01 ` Matt 2024-02-01 15:56 ` Ihor Radchenko 2024-02-01 15:50 ` Ihor Radchenko 1 sibling, 1 reply; 11+ messages in thread From: Matt @ 2024-01-27 22:01 UTC (permalink / raw) To: ihor radchenko; +Cc: emacs-orgmode, "Sławomir Grochowski" ---- On Thu, 25 Jan 2024 23:33:53 +0100 Ihor Radchenko wrote --- > I do not have a strong opinion here though. If more people chime in here > and support re-arrangement, I will not oppose. I think Sławomir makes a good case for moving it. What concepts are used and where are they introduced in the manual? - [X] TODO + Mentioned in Section 1.5 [[https://www.gnu.org/software/emacs/manual/html_node/org/Conventions.html][Conventions]] - [ ] Properties + Mentioned in Section 2.7 [[https://www.gnu.org/software/emacs/manual/html_node/org/Drawers.html][Drawers]] + Explained in Section 7.1 [[https://www.gnu.org/software/emacs/manual/html_node/org/Property-Syntax.html][Property Syntax]] - [X] Headlines + Explained in Section 2.1 [[https://www.gnu.org/software/emacs/manual/html_node/org/Headlines.html][Headlines]] TODOs, Properties, and headlines are talked about in the Checkboxes section. Section 2.7 introduces properties. We're proposing inserting Checkboxes into position 2.6.1. This would mean a concept used wouldn't be defined yet. Out of time tonight so I don't have any suggestions for how to address it yet. > In fact, Checkboxes section of the manual was previously under Document > structure. This was changed in release_4.45. > https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=6a9c670d I checked the mailing list around that time for any issues that might mention checkboxes and didn't find anything. On 2008-01-27, they were discussing results of a recent survey. I was able to find a copy from the week after the change. I didn't see anything that would have motivated the change. Here's the archived survey. It's interesting. https://web.archive.org/web/20080202231951/https://orgmode.org/survey.html -- Matt Trzcinski Emacs Org contributor (ob-shell) Learn more about Org mode at https://orgmode.org Support Org development at https://liberapay.com/org-mode ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2024-01-27 22:01 ` Matt @ 2024-02-01 15:56 ` Ihor Radchenko 0 siblings, 0 replies; 11+ messages in thread From: Ihor Radchenko @ 2024-02-01 15:56 UTC (permalink / raw) To: Matt; +Cc: emacs-orgmode, Sławomir Grochowski Matt <matt@excalamus.com> writes: > > In fact, Checkboxes section of the manual was previously under Document > > structure. This was changed in release_4.45. > > https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=6a9c670d > > I checked the mailing list around that time for any issues that might mention checkboxes and didn't find anything. On 2008-01-27, they were discussing results of a recent survey. I was able to find a copy from the week after the change. I didn't see anything that would have motivated the change. 2008-01-31 is the first commit in Org git repository. So, the discussion may be any time before that date. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples 2024-01-27 20:55 ` Sławomir Grochowski 2024-01-27 22:01 ` Matt @ 2024-02-01 15:50 ` Ihor Radchenko 1 sibling, 0 replies; 11+ messages in thread From: Ihor Radchenko @ 2024-02-01 15:50 UTC (permalink / raw) To: Sławomir Grochowski; +Cc: Bastien, emacs-orgmode Sławomir Grochowski <slawomir.grochowski@gmail.com> writes: > I noticed in my patch that I moved the description ("The ‘[2/4]’ and > ‘[1/3]’ in") of an example. > And it should be just below the example. > > So I'm sending a fixup! patch to fix this. > It's my first fixup! patch so I hope this is the right procedure ;) Thanks! Applied, onto main. https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=614d534a9 -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2024-02-01 15:54 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-11-06 12:50 [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples Sławomir Grochowski 2023-11-06 16:49 ` Bastien 2023-11-06 17:05 ` Ihor Radchenko 2023-11-06 17:19 ` Bastien 2023-11-07 17:30 ` Sławomir Grochowski 2023-11-07 23:36 ` Bastien Guerry 2023-11-08 6:36 ` Sławomir Grochowski 2024-01-27 20:55 ` Sławomir Grochowski 2024-01-27 22:01 ` Matt 2024-02-01 15:56 ` Ihor Radchenko 2024-02-01 15:50 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).