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

[Ihor Radchenko]

Matt  writes:

>  >...or did you not provided arguments /why/ the
>  > section should be moved? I need to understand what kind of improvement
>  > it would provide to the manual.
>
> I didn't know that's what you were looking for.  When I said, "I had 
> responded in favor..." it was in response to your prior message which said,

Let me clarify.
I am personally neutral about where the concept of checkboxes is
introduced. Either way is generally possible.

However, moving "Checkboxes" section will require some work. We will
need to make sure that the overall flow of the manual is _improved_.
The question is how to judge "improved".

>From my point of view, the manual will be improved by the proposed
change if (a) we can see clear logical argument why the proposed
rearrangement is superior; or/and (b) *a number* of Org users /feel/ that
the rearrangement will improve thins.

Your response is in favor, but you did not appear to present logical
arguments. So, I classify your response as if you /feel/ that the
rearrangement will be better. Such response of a single person is not
very convincing. I'd only see rearrangement justified if many users are
in favor.

Another question is when there is a clear logical argument. Such
argument would not require multiple users to agree as it would stand by
its own.

>> No comments arrived within one month. 
>
> This is incorrect albeit understandable.  I had responded and, therefore, 
> there were not "no comments."  However, it looks like I responded in the 
> wrong thread! ("Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox 
> states examples")  That's my bad! 

I indeed missed your comment when writing this particular sentence.

> Regarding reasoning, I'm in favor of the move for the reasons Sławomir gave:
>
>> 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'.
>
> The issue is checkbox usage is split between different sections of the manual.
>
> You had responded to this by saying,
>
>> Both arrangements are logical. Checkboxes are useful as a complement to
>> TODO items. And they are also indeed a plain list feature.
>
> It seems we're all agreed the proposed arrangement is logical and that the 
> issue is valid.  I don't think it needs extra justification.

Yes, the proposed arrangement is logical. So is the existing
arrangement. The problem is that I do not see why the proposed
arrangement is *better*.

> Conceding this point, which we all appear to, the issue becomes which 
> arrangement we should use?
>
> Originally, we were reluctant to move the Checkboxes section only because 
> Carston had moved it previously.  Unfortunately, we don't know *why* Carston 
> moved it.  This isn't a very contestable justification.

I agree.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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

[Matt]

  On Wed, 28 Feb 2024 13:17:54 +0100  Ihor Radchenko  wrote --- 
 > Matt m...@excalamus.com> writes:
 > 
 > > I had responded in favor here: 
 > > https://list.orgmode.org/18d4cf138a6.10fb9c6702382826.5023996590743168...@excalamus.com/
 > 
 > Did I miss something...

Yes, it appears there's a little bit of a mix up because of a bad subject line. 
 There's also some nitpicky logic.  The tl;dr is, we shouldn't use the current 
patch.

 >...or did you not provided arguments /why/ the
 > section should be moved? I need to understand what kind of improvement
 > it would provide to the manual.

I didn't know that's what you were looking for.  When I said, "I had responded 
in favor..." it was in response to your prior message which said,

> No comments arrived within one month. 

This is incorrect albeit understandable.  I had responded and, therefore, there 
were not "no comments."  However, it looks like I responded in the wrong 
thread! ("Re: [PATCH] doc/org-manual.org: Checkboxes, add checkbox states 
examples")  That's my bad! 

Regarding reasoning, I'm in favor of the move for the reasons Sławomir gave:

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

The issue is checkbox usage is split between different sections of the manual.

You had responded to this by saying,

> Both arrangements are logical. Checkboxes are useful as a complement to
> TODO items. And they are also indeed a plain list feature.

It seems we're all agreed the proposed arrangement is logical and that the 
issue is valid.  I don't think it needs extra justification.

Conceding this point, which we all appear to, the issue becomes which 
arrangement we should use?

Originally, we were reluctant to move the Checkboxes section only because 
Carston had moved it previously.  Unfortunately, we don't know *why* Carston 
moved it.  This isn't a very contestable justification.

My latest reply gives a specific reason to *not* apply the current patch.  That 
is, to *not* move the Checkbox section as-is.  The reason is:

 > > The Checkboxes section is written assuming the reader knows what 
 > > Properties are.  The GNU documentation guidelines suggest writing as 
 > > though readers have read from the beginning [fn:1] [fn:2].  That is, 
 > > unless introducing a concept, only use concepts that have already been 
 > > explained.  Properties are introduced in Section 2.7 and Checkboxes is 
 > > currently 5.6.   The proposal is to move Checkboxes to 2.6.1 *before* 
 > > properties are introduced.  This is a problem.

I suspect this is the reason Carston moved the section.  Regardless, it's a 
valid reason to have moved it and gives us clear criteria for why we can't 
apply the patch.  It also gives us a precise target for what would need to be 
fixed in order to resolve the issue of checkbox usage being split between 
sections by moving the Checkbox section.

 > We start talking about properties as early as in 2.2.2 Initial
 > visibility and in many other places. Re-ordering the manual to avoid
 > referring to future concepts would entail a major rewrite.

I believe that arranging documentation in conceptual order is always a 
worthwhile goal.  It's obviously better to have concepts introduced in order.   
It's also completely reasonable to not want to do that work right now.  I'm not 
willing to at the moment and it sounds like you aren't either.  That's okay.  
If Sławomir or someone else wants to, I still think the original point is 
valid.  However, the proposed patch, moving the section as-is, won't work 
because it (re)introduces problems with conceptual ordering.

If someone wants to suggest a patch which resolves the issue of checkbox usage 
being split between sections which preserves, or improves, the conceptual 
order, I'd be happy to assist.

--
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): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

[Ihor Radchenko]

Matt  writes:

> I had responded in favor here: 
> https://list.orgmode.org/18d4cf138a6.10fb9c6702382826.5023996590743168...@excalamus.com/

Did I miss something, or did you not provided arguments /why/ the
section should be moved? I need to understand what kind of improvement
it would provide to the manual.

> The Checkboxes section is written assuming the reader knows what Properties 
> are.  The GNU documentation guidelines suggest writing as though readers have 
> read from the beginning [fn:1] [fn:2].  That is, unless introducing a 
> concept, only use concepts that have already been explained.  Properties are 
> introduced in Section 2.7 and Checkboxes is currently 5.6.   The proposal is 
> to move Checkboxes to 2.6.1 *before* properties are introduced.  This is a 
> problem.

We start talking about properties as early as in 2.2.2 Initial
visibility and in many other places. Re-ordering the manual to avoid
referring to future concepts would entail a major rewrite.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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

[Sławomir Grochowski]

Matt  writes:

That's good point. Thank you Matt for links. 
> However, before moving the section we'd need to find a way to introduce 
> properties before the checkboxes section.
>
> The Checkboxes section is written assuming the reader knows what Properties 
> are.  The GNU documentation guidelines suggest writing as though readers have 
> read from the beginning [fn:1] [fn:2].  That is, unless introducing a 
> concept, only use concepts that have already been explained.  Properties are 
> introduced in Section 2.7 and Checkboxes is currently 5.6.   The proposal is 
> to move Checkboxes to 2.6.1 *before* properties are introduced.  This is a 
> problem.
>
> [fn:1] https://www.gnu.org/prep/standards/standards.html#Documentation
> [fn:2] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

Let's close this thread for now. Because in the patch I uploaded, it's too
much of changes + relocation. 

I think that first we need to simplify a bit, improve section '5.6
Checkboxes' - because currently it starts with a very complicated
example and its description. 
And checkbox is quite simple feature.

So in a new thread I will post the changes regarding '5.6 Checkboxes'. 
And then later we could consider relocating.

-- 
Sławomir Grochowski

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

[Matt]

  On Mon, 26 Feb 2024 09:56:44 +0100  Ihor Radchenko  wrote --- 
 > Ihor Radchenko yanta...@posteo.net> writes:
 > 
 > > I do not have a strong opinion here though. If more people chime in here
 > > and support re-arrangement, I will not oppose.
 > 
 > No comments arrived within one month. Does not look like people care
 > much about this. So, let's preserve the existing structure of the
 > manual.
 > 
 > Canceled.
 
I had responded in favor here: 
https://list.orgmode.org/18d4cf138a6.10fb9c6702382826.5023996590743168...@excalamus.com/

However, before moving the section we'd need to find a way to introduce 
properties before the checkboxes section.

The Checkboxes section is written assuming the reader knows what Properties 
are.  The GNU documentation guidelines suggest writing as though readers have 
read from the beginning [fn:1] [fn:2].  That is, unless introducing a concept, 
only use concepts that have already been explained.  Properties are introduced 
in Section 2.7 and Checkboxes is currently 5.6.   The proposal is to move 
Checkboxes to 2.6.1 *before* properties are introduced.  This is a problem.

[fn:1] https://www.gnu.org/prep/standards/standards.html#Documentation
[fn:2] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

--
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): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

[Ihor Radchenko]

Ihor Radchenko  writes:

> I do not have a strong opinion here though. If more people chime in here
> and support re-arrangement, I will not oppose.

No comments arrived within one month. Does not look like people care
much about this. So, let's preserve the existing structure of the
manual.

Canceled.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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

[Ihor Radchenko]

Sławomir Grochowski  writes:

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

Both arrangements are logical. Checkboxes are useful as a complement to
TODO items. And they are also indeed a plain list feature.

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

So, I am slightly reluctant to revert the change that was previously
made - I presume that Carsten had reasons to move things around.

I do not have a strong opinion here though. If more people chime in here
and support re-arrangement, I will not oppose.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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

[Sławomir Grochowski]

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