Re: Convert README.org to plain text README while installing package

[Tim Cross]

Jean Louis <bugs@gnu.support> writes:

> * Tim Cross <theophilusx@gmail.com> [2022-06-08 09:57]:
>> Please give me an example of org mode 'not make space where it would be
>> otherwise required'. Can you provide a single example of org mode
>> syntax which is not readable in any text editor. There are quite a few
>> projects on Github/Gitlab which have readme.org files - can you point to
>> one which cannot be read with a plain text editor? 
>
> Hello Tim,
>
> my response time is not so fast.
>
> I am now reviewing package descriptions:
>
> Recommended for everybody to read:
>
> Usability 101: Introduction to Usability
> https://www.nngroup.com/articles/usability-101-introduction-to-usability/
>
> Usability Testing 101
> https://www.nngroup.com/articles/usability-testing-101/
>

I gues sour differences here are that you have conflated issues of
readabiity and usability into the definition of plain text. Few of the
criticisms you have raised IMO are specific to org mode or due to org
modes syntax. Many of them are due to the individual author's layout
and not the result of org mode syntax. You can also write documents
which are very difficult to read using just plain ASCII. They are both
plain text.

I also think you are over-stating the difficulty of reading the raw org
file contents. While I would agree they are asier to read when correctly
formatted, they are not impossible to understand without it. For example,
to say something like 

> package corfu, totally not human readable as it begins with:

> #+title: corfu.el - Completion Overlay Region FUnction
> #+author: Daniel Mendler
> #+language: en
> #+export_file_name: corfu.texi
> #+texinfo_dir_category: Emacs
> #+texinfo_dir_title: Corfu: (corfu).
> #+texinfo_dir_desc: Completion Overlay Region FUnction

is I think totally over stating the situation. I showed the above to
someone who is not a technical person and only uses computers for email,
web and office work and they were able to understand it perfectly well.
They didn't know what the texinfo lines meant, but they understood what
the title was, who the author was, the language and even the
texinfo_dir_desc being a description. I think most people are far more
capable at reading such information than you assert. They might not
understand all of it, but then again, I often read documents where I
don't understand all of it. The point is, there is a big difference
betrween being able to read contents and understand them. 

As a comparison, consider some RFCs which you mentioned previously. I've
read RFCs which perfectly comply with the formatting you referenced that
were (to me) totally unintelligible. Sometimes this is because the
writing is poor or the concepts are too alien or it is simply too
complicated for my limited understanding. However, this is still a plain
text document.  

For me, a file is plain text if you can edit and save it using just a
plain text editor and the file will still be valid. I also consider HTML
files to be plain text, (but far less readable than org files). On the
other hand, *.docx are not plain text and cannot be edited with a plain
text editor, saved and still be valid. Likewise, other formats which
use non-printable control characters are not plain text.

I will try to be clearer when I say something is plain text. Readability
and useability are separate from file formats - they are a higher, but
related, concern. Plain text does not imply anything about readability
or usability other than a plain text file can be opened and physically
read using a plain text editor or a utility like 'cat'. The ability of
the individual to interpret that information does not affect whether it
is plain text. If, for example, you write lots of HTML, an HTML file is
easily understood when displayed with cat. 

Of course, appropriate formatting within a plain text document can
affect how easily the document can be read and I think it is good to try
and format the document to be as easy to read as possible. However, for
org mode, this is really under the control of the author. Org data files
can be formatted in a way which makes them easier to read and there are
various Emacs settings which can be used which affects this (wrap,
visual line mode, adding blank lines at the end of sections etc). The
point is, many of your criticisms are not due to org syntax or org
enforced forrmatting, which is one reason I disagree with assertions
that org files are not plain text.

I'm sure this is apoint we will never agree on, so happy to leave it there.