Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)

[Ihor Radchenko]

Matt <matt@excalamus.com> writes:

> Several things in the first paragraph unrelated to your changes stick
> out to me. I can't help but make some other remarks.
>
> "TODO" should probably be "to-do".  Every dictionary I looked in has
> an entry for "to-do".  I think that's the common spelling.

Yet, we consistently use TODO keyword and TODO list across the whole
manual. Stackexchange tells that both variants are valid:
https://english.stackexchange.com/questions/46217/todo-list-or-to-do-list
although "todo" is much less widely used.

I do not see much benefit changing "todo list" to "to-do list". Both are
clear and both are grammatically correct.

> Regarding "markup language," that reads to me like programmer jargon.
> What does it mean and why should someone care?  Again, who are we
> writing to?  A markup language is a notation for formatting,
> structure, and relationships.  I think it would be best to directly
> say that.

What about "plain text file format"?

> I would also soften that Org "relies" on its markup.  It doesn't.  I
> used Org only for lists for a long time.  I believe lists to be a
> fundamental feature of Org (and hence a great item for the first
> sentence).  Lists are as simple as dashes.  It's hard to say that
> dashes before list items is a markup language.

Yet, it is. You cannot, for example, use "." as bullets in Org mode.
Also, indentation matters in Org lists, while it does not matter in more
free-style writing.

> Finally, I don't think the file extension is relevant for the first
> paragraph.  Technically, an extension isn't necessary.  A person can
> call M-x org-mode or use a file local variable.  Worse, I think the
> extension contradicts the point that any text editor can view an Org
> file.  Ever try to open a .org file in Windows?  It asks for the
> program.  Yes, *technically* Windows could open a .org file *if* the
> person opening it knew which program to use (or to change the
> extension to something like .txt).  Again, who are we writing to?  If
> it's someone who believes file extensions matter, then this would
> introduce unnecessary friction.  It seems best to avoid it.  Better to
> do as you've done and say Org is readable (which it is) rather than
> specify the extension (which doesn't really matter).

I am mostly neutral here, but I can see an argument why mentioning .org
extension may be useful - unlike Windows, GitHub does expect .org file
extension specifically to render Org mode files. The same goes for
non-Emacs editors that support Org markup. For example, Vim/Neovim.

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