[PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Sławomir Grochowski]

[-- 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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Bastien]

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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Ihor Radchenko]

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>

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Bastien]

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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Sławomir Grochowski]

[-- 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 --]

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Bastien Guerry]

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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Sławomir Grochowski]

[-- 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 --]

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Sławomir Grochowski]

[-- 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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Matt]

 ---- 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

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Ihor Radchenko]

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>

Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states examples

[Ihor Radchenko]

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>