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

[Carsten Dominik <carsten.dominik@gmail.com>]

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