Re: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable

[Matt <matt@excalamus.com>]

 ---- On Fri, 05 Jan 2024 14:04:17 +0100  Ihor Radchenko  wrote --- 

 > Thanks for the comments!
 > I am attaching the next iteration of the patch.

Looks good

 > Matt matt@excalamus.com> writes:
 > 
 > > +Org Mode is an authoring tool and a to-do lists manager for GNU Emacs.
 > > +It uses a legible plain-text notation to show formatting, structure,
 > > +relationships.  Anyone able to edit text can write using Org.  Anyone
 > > +able to read text can view it.
 > 
 > As a non-native speaker, I have some difficulties understanding
 > "legible" meaning in this context. 

How does it come across to you?

 > Also, "anyone able to read text can
 > view it" would be a bit of a bold claim, I think. So, I went with more
 > moderate wording.
 
Good call.  That whole sentence is a mess.  When I wrote "anyone able to read text", I intended to say something like "if a computer can render the text".  However, that reduces to "if a computer can render it, then you can view it" which isn't very impressive.

When you say Org markup is "human-readable", I see that coming from it being plain-text.  It requires no special tools.  It's readable like "accessible, easily obtained".  I'm contrasting that with Jupyter Notebooks.  I think this aspect of readability is something we should emphasize.

Readability also means that what's written can be inferred without referencing other sources.  It's readable like "apparent, easily understood".  I think this is probably what you're thinking of.

What do you mean by "human-readable"?

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