From: Matt <matt@excalamus.com>
To: "Ihor Radchenko" <yantar92@posteo.net>
Cc: "\"Sławomir Grochowski\"" <slawomir.grochowski@gmail.com>,
emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: [PATCH] doc/org-manual.org (Checkboxes): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists'
Date: Wed, 28 Feb 2024 20:10:54 +0100 [thread overview]
Message-ID: <18df1207a7b.115a993991531101.8492317175658336513@excalamus.com> (raw)
In-Reply-To: <87le743hli.fsf@localhost>
---- 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
next prev parent reply other threads:[~2024-02-28 19:12 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-25 13:05 [PATCH] doc/org-manual.org (Checkboxes): move section 'Checkboxes' from 'TODO Items' to 'Plain Lists' Sławomir Grochowski
2024-01-25 22:36 ` Ihor Radchenko
2024-02-26 8:59 ` Ihor Radchenko
2024-02-27 16:47 ` Matt
2024-02-27 23:07 ` Sławomir Grochowski
2024-02-28 12:20 ` Ihor Radchenko
2024-02-28 19:10 ` Matt [this message]
2024-03-02 12:43 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=18df1207a7b.115a993991531101.8492317175658336513@excalamus.com \
--to=matt@excalamus.com \
--cc=emacs-orgmode@gnu.org \
--cc=slawomir.grochowski@gmail.com \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).