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

[Matt <matt@excalamus.com>]

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