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

[Po Lu]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

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

So what was the purpose of the following statement?

>> Spend the time to go through the key bindings listed in the org
>> manual

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

IMO, packages should provide a plain text README, alongside a rich text
version in a relatively standard format like HTML.

By using HTML, it becomes readable not only in Emacs, but also any other
program that understands HTML.  HTML is also understood by many more
people than Org mode.

It's okay for package maintainers to write their documentation using
Org, and then to export it to HTML.  But please don't insist that all
documentation be written using Org mode, or that it's okay for packages
to only provide documentation in that format.