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

[Philip Kaludercic]

Tim Cross <theophilusx@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Tim Cross <theophilusx@gmail.com> writes:
>>
>>> 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'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.
>>> 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.
>>
>> I have consult installed, and if I want to read the package summary
>> generated by C-h P, I half of the buffer is just Org configuration:
>>
>> #+title: consult.el - Consulting completing-read
>> #+author: Daniel Mendler
>> #+language: en
>> #+export_file_name: consult.texi
>> #+texinfo_dir_category: Emacs misc features
>> #+texinfo_dir_title: Consult: (consult).
>> #+texinfo_dir_desc: Useful commands built on completing-read.
>>
>> #+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU
>> Emacs"
>> src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
>> #+html: <a href="http://elpa.gnu.org/packages/consult.html";><img
>> alt="GNU ELPA" src="https://elpa.gnu.org/packages/consult.svg"/></a>
>> #+html: <a href="http://elpa.gnu.org/devel/consult.html";><img
>> alt="GNU-devel ELPA"
>> src="https://elpa.gnu.org/devel/consult.svg"/></a>
>> #+html: <a href="https://melpa.org/#/consult";><img alt="MELPA"
>> src="https://melpa.org/packages/consult-badge.svg"/></a>
>> #+html: <a href="https://stable.melpa.org/#/consult";><img alt="MELPA
>> Stable"
>> src="https://stable.melpa.org/packages/consult-badge.svg"/></a>
>>
>> * Introduction
>> :properties:
>> :description: Why Consult?
>> :end:
>> #+cindex: introduction
>>
>> While plain text, it is not what I am interested in at this point.
>
> and in what seems to be typical in this thread, you have selected an
> extreme example to demonstrate your point. This is definitely not a
> typical README.org file - at least not from my experience. 

While true, I don't get why this is a problem.  I don't think making the
package developers simplify their READMEs would a better solution, since
they are also frequently used to generate manuals.  

As to whether or not the package description should be the same as the
manual, is a different question (I am inclined to think the package
description should be a brief summary of a few paragraphs at most).