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

[Kévin Le Gouguec]

Po Lu <luangruo@yahoo.com> writes:

> Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:
>
>> 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

Cannot speak for Alan nor Tim, but my understanding of the exchange that
led to the bit you quote is that Tim was inviting Alan to check how many
of these 784 bindings had any relevance to the topic under discussion
(navigating and, to a lesser extent, authoring Org READMEs) in order to
show that "M-x org TAB" was not a good heuristic to assess how much
complexity _needs_ to be shoved onto an unsuspecting README reader.

In Tim's own words (a bit before the one you quote):

> That 750 key bindings is an extreme over statement and not what is being
> proposed.

So your paraphrasing ("expecting someone to go through the entire Org
manual in order to write and edit README files") struck me as
disconnected from (my own understanding of) Tim's argument: AFAIU,

* he wasn't saying _Org users_ need to go through the manual,

* he was confronting the "784 bindings" argument by saying it was not a
  particularly useful heuristic, inviting _us_ (participants of the
  present discussion) to check for ourselves what proportion of these
  bindings are actually relevant to the discussion.

Again though, cannot speak for Tim; I can only explain my undertanding
of the discussion, and why I was dumbfounded by your reply.

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

If there's been advocating for all documentation to be written in Org,
I've (dis)missed that, so sorry for not following closely enough.

As for packages only providing documentation in Org: again, I think the
way forward is automation at the package archive level.  Asking authors
to maintain two sync'ed READMEs stands a small chance of success IMO.