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