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

[Kévin Le Gouguec]

Po Lu <luangruo@yahoo.com> writes:

> Tim Cross <theophilusx@gmail.com> writes:
>
>> 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. 
>
> What's more odd is expecting someone to go through the entire Org manual
> in order to write and edit README files.

This thread has been a bit disheartening to read from the sidelines; as
much as I empathize with wanting to keep Emacs accessible by avoiding
code bloat and keeping cognitive load low, it is hard to know what to
reply to statements such as this one.

No one has ever had to "go through the entire Org manual in order to
write and edit README files".  Just like no one has ever had to read the
Emacs manual cover-to-cover in order to do anything with it (they _can_,
of course, but they don't _have to_).

My first years with Org were spent using (1) TAB folding (2) outline
navigation commands, and that's it.  We already have *Help* commands
which combine those features on the development branch: see C-h b with
the recently added describe-bindings-outline user option.


I don't see how enabling these section-folding and navigation features
could hurt the accessibility of package READMEs written in a structured
format.  Alan rightly points out that Org overreaches with unhelpful key
bindings, and the benchmarks posted earlier show that loading Org
wholesale for displaying READMEs would be irksome; to me that merely
suggests that whatever subset of Org features we find relevant for
_consulting_ READMEs should be better modularized.

So I would expect the discussion to focus on:

(1) what this subset should be (e.g. should it include font-locking),

(2) whether we want to add "escape hatches" for whoever struggles with
    those "rich" READMEs.

    E.g. a package-show-plain-readmes option, which could do any number
    of things depending on the underlying markup format.  For Org
    specifically, it could pass the README through the (ill-named, and
    not limited to ASCII) org-ascii-export-as-ascii, which converts Org
    markup to something more appropriate for font-lock-less viewing
    (sections underlined with equals and hyphens; inline links moved to
    their own paragraphs).

    It might even make sense for (Non)GNU ELPA to automatically run that
    function on Org READMEs in order to ensure the "bare" variant is
    always instantly available to package users.


Instead it feels like a lot of words are spent on

(1) Org is bloated and complex: yes, agreed,

(2) Package maintainers should give users the courtesy of maintaining
    two READMEs: no, I don't see a universe where that will fly.


I hope at the end of all this, we can find some middle ground between
maintainers who happen to find their productivity increased by using
Org, and maintainers who cringe at every cycle their CPU spends on Org
code.  I believe this middle ground exists.