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

[Alan Mackenzie <acm@muc.de>]

Hello, Tim.

On Mon, Jun 06, 2022 at 23:57:55 +1000, Tim Cross wrote:

> Alan Mackenzie <acm@muc.de> writes:

> > Hello, Tim.

> > On Mon, Jun 06, 2022 at 10:19:38 +1000, Tim Cross wrote:

[ .... ]

> >> 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 just fine without doing any
> configuration at all. 

I find emacs -Q to be all but unusable, except for testing things with.
Only with my configurations does it become (for me) usable.  I expect the
same to hold for other users.

> >> .... 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 proposed here is that a read only buffer will use org mode
> to format/display the content. Very simple and not the monster you
> insist. 

"Very simple" has a habit of becoming increasingly complicated over time.

> >> 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 contents of this
> read-only buffer. There will not be huge numbers of
> unwanted/unexpected key bindings .....

For how long?  Politically, org mode is not part of the Emacs core - it
is an add on application for those that want it.  If the maintainers of
org mode wanted to push it into the Emacs core, then they would proceed,
firstly, by getting a foot in the door, then steadily increasing pressure
to add more and more until org mode was in the position, say, that Info
currently is.  This must not happen (for reasons discussed below).

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

Hmm.

> >> 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 modes - none of
> which are relevant to a READM.org ile (for example, all the key
> bindings relating to agenda mode). 

I see many of these bindings as context dependent, with the name of the
function named after the key sequence, not the functionality - e.g.
org-shiftcontroldown.  That is not the way the rest of Emacs is
constructed.  I hate context dependence (except when it is properly
implemented, e.g. by major modes).

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

There are only so many hours in the day.  I do not "admit" not spending
the time learning it, since there is nothing shameful about this.  I
state it as a fact.  I do not want to spend/waste time on it, and it is
my fear I will be forced into it by a stealthy increase in org mode's
prevelance, if I do not protest.

> This seems like an arguument based on fear and uncertainty about
> something you don't know rather thaa one based on fact.

I put org.org into a buffer.  I saw lots of lines ending in ..., which is
fair enough.  I try C-c C-s to show a subtree, and instead get a calendar
in a new window.  Brilliant!  Did I mention I hate context dependent
commands?  So I have to type M-x outline-show-subtree, which works.  I
read the screenful of text, then type C-S-<down> to scroll it up.
Instead of my standard scrolling command, I get an error message about
"Not at a clock log".  Org mode has stolen the key sequences
C-S-<up>/<down>, amongst many others.  So how am I meant to scroll text?

And so on.  Without some serious configuration, org mode is for me
unusable.  Moving commands around key sequences would be a nightmare,
given the 784 commands (or even the 230 counted by Eli).  And moving
org-shiftcontroldown onto a different key sequence, assuming I could find
one, would make the function name meaningless.

> 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
> understand the basics before condemnation. 

I see what looks like an attempt to force org mode into the Emacs core by
stealth, a bit at a time.  Already you are talking about adding
functionality for folding.

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

And then after adding folding (by some mysterious key sequence), some
bright spark will want to add something else "for large readme files".
The consequence will be large READMEs which cannot be conveniently read
without this new feature.  And so it goes on.

We already have a format in Emacs for big documentation, Info.  Info has
about 40 commands, not 230 or 784.

> > "It" could best be avoided by having plain text README files.

I think we should strongly encourage package writers to include plain
text READMEs in their packages.

-- 
Alan Mackenzie (Nuremberg, Germany).