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

[Tim Cross]

Alan Mackenzie <acm@muc.de> writes:

> Hello, Tim.
>
> On Mon, Jun 06, 2022 at 10:19:38 +1000, Tim Cross wrote:
>
>> Michael Albinus <michael.albinus@gmx.de> writes:
>
>
>> > I have no problem if there are structured README.org or README.md
>> > files in parallel. But a README file should be plain text.
>
> I agree with this.
>
>> I've seen this mentioned multiple times in this thread and it doesn't
>> make sense to me. 
>
>> Org files *are* plain text. This is one of (perhaps the biggest) selling
>> points for org mode. They don't use any form of 'binary' data and can be
>> read just fine in any text editor or just using cat/less/more whatever.
>
> We're reduced to arguing about the meaning of "plain text".  The way I
> see it, plain text means to be read as is by the user.  In that sense,
> the formats you mention below, xml, html, etc. are _not_ plain text -
> they're designed for machine processing.  A typical spam email in HTML
> has the human readable pieces swamped by the machine readable pieces.  I
> think you're arguing that this isn't the case with org mode files, though
> Philip Kaludercic pointed out an org file where this wasn't the case.
>

Philip's example is an extreme case and not representative of normal
README.org files. 

>> They may look a little *ugly*, especially with respect to URLs, but are
>> still quite readable - a lot more readable than other plain text formats
>> such as xml or html or json etc.
>
> And their performance in standard programs like grep, wc, etc. is that
> much worse than plain text.


No, I disagree with this completely. Org mode markup is very simple and
rarely has any impact with regards to grep, ag or any other 'shell' tool
It is precisely why I consider it to be a plain text format  - all of
these standard plain trext processing tools work in the main just as
well as they do on any ASCII file. Again, org mode is not like XML or
HTML or other formats which do make such processing difficult. 
>
>> I also find arguments based around org being complex and difficult to
>> learn to be somewhat overstated.
>
> There are 784 key bindings in org mode.  How can you say that this isn't
> complex and difficult to learn?
>
Very simply because the vast majority of  those key bindings only come
into play when yhou use advanced features of org mode, such as the
agenda or table editing or noweb mode. If your just using basic org mode
features, very very few of those key bindings even come into play. Just
go throgh that list and remove any bindings relating to agenda mode,
table editing mode, source block modes, clock table mode, list editing
mode, etc and you end up with very few key bindings (all of which are
udner the C-c prefix, unlike your previous claim). 

>> Org is powerful and very configurable, ....
>
> That contradicts your previous statement to some extent.  Any program
> which is very configurable _needs_ to be configured.
>

ABsolute nonsense. Just because you can configure somethig doesn't
automatically mean you have to configure it. Emacs is extremely
configurable, but you can use it jsut fine without doing any
configuration at all. 

>> .... which means there can be a lot to learn if you want to leverage
>> off all it has to offer.
>
> I don't want to do this.  I want to avoid org mode being loaded into my
> Emacs; it fouls up my key bindings to a significant extent.  Particularly
> if I just want to read a 50 line README.
>

Other posts have already explained this is NOT what is being proposed
and that it would not affect your key bindings in the slightest. All
that is being propsoed here is that a read only buffer will use org mode
to format/display the content. Very simple and not the monster you
insist. 


>> However, like emacs, the basics are very simple and easy to learn. 
>
> I don't agree that the basics of Emacs are simple and easy to learn at
> all.  That's a strong reason why other editors have become popular.  Why
> should I have to spend time learning a super-complicated mode just to
> read a 50 line README?
>

Well, basically, you don't. That has already bene explained and does not
need to be reitterated here. However, to be clear, all that is being
proposed is that org formatting is applied to the contgents of this
read-only buffer. There will not be huge numbers of
unwanted/unexptrected key bindings and there won't be a huge number of
other changes. You will likely have some additional key bindings which
may make navigating larger README files easier and that is about it. All
that is really being proposed here is org font locking and outline mode
navigation. All very simple really. 

>> While I'm not arguing that org should be forced upon everyone ....
>
> If a README file is README.org, then org mode is forced upon anybody
> wishing to read it in Emacs.  This is why README files should be plain
> text.
>
>> .... and I would agree we need to keep potential load time issues in
>> mind, there seems to be lots in this thread over stating the issues and
>> jumping to extremes.
>
> I think org mode is an extreme, with its 784 key bindings which seem to
> violate written and unwritten conventions.


That 750 key bindings is an extreme over statement and not what is being
proposed. Yet again, people jumping to extremes based on ignorance and
paranoia. Spend the time to go through the key bindings listed in the
org manual and you will soon realise that the majority of those bindings
only come into effect in specialised mdoes - none of which are relevant
to a READM.org ile (for example, all the key bindings relating to agenda
mode). 

I find it odd that someone can on one hand argue so hard against using a
mode based on the complexity and vast nubmer of key bindings and at the
same time admit they have never spent the time to learn the mode. This
seems like an arguument based on fear and uncertainty about something
you don't know rather thaa one based on fact. Perhaps look more closely
at what was actually being proposed (which was not a full org mode
situation) and spend enough time to at least udnerstand the basics
before condemnation. 
>
>> All that seems to really be under consideration is to enable rendering
>> of *org files in help buffers using org font locking and perhaps
>> enabling folding, which could be very beneficial for large readme files
>> and would not matter for small ones. I also suspect this is something
>> which could be disabled with a simple variable setting for those who
>> really don't like it. 
>
> "It" could best be avoided by having plain text README files.