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

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

[Sławomir Grochowski]

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

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

[Ihor Radchenko]

Sławomir Grochowski <slawomir.grochowski@gmail.com> 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 <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): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

[Ihor Radchenko]

Ihor Radchenko <yantar92@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.

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

[Matt]

 ---- On Mon, 26 Feb 2024 09:56:44 +0100  Ihor Radchenko  wrote --- 
 > Ihor Radchenko yantar92@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.5023996590743168415@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'

[Sławomir Grochowski]

Matt <matt@excalamus.com> 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'

[Ihor Radchenko]

Matt <matt@excalamus.com> writes:

> I had responded in favor here: https://list.orgmode.org/18d4cf138a6.10fb9c6702382826.5023996590743168415@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 <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): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

[Matt]

 ---- On Wed, 28 Feb 2024 13:17:54 +0100  Ihor Radchenko  wrote --- 
 > Matt matt@excalamus.com> writes:
 > 
 > > I had responded in favor here: https://list.orgmode.org/18d4cf138a6.10fb9c6702382826.5023996590743168415@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 <matt@excalamus.com> 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 <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): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 3690 bytes --]

On Sat, Mar 2, 2024 at 1:40 PM Ihor Radchenko <yantar92@posteo.net> wrote:

> Matt <matt@excalamus.com> 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.
>

Checkboxes are meta data that is related to actions. Introducing checkboxes
in the "Structure -> Plain lists" section would be similar to introducing
TODO keywords in the "Headlines" section. Like you, I can find arguments
for both arrangements - but this was the reasoning I used when I structured
the manual.

- Carsten


>
> I agree.
>
> --
> 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>
>
>

[-- Attachment #2: Type: text/html, Size: 4892 bytes --]