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

[Protesilaos Stavrou]

Hello Philip,

> From: Philip Kaludercic <philipk@posteo.net>
> Date: Tue, 07 Jun 2022 12:07:21 +0000
>
>> As far as I am concerned, the README.org is a fully fledged resource,
>> not a generic, "here are the absolute basics" kind of file (not that
>> there is anything wrong with those).  As such, writing a separate
>> README, instead of exporting README.org into plain text, would add to
>> the maintenance burden---I would rather avoid that.
>
> Most packages already come with a commentary section.  While these
> sometimes just say "read the readme" and others contain unnecessary
> information like how to install the package, many are well written and
> give the appropriate, initial pointers for getting started with a new
> package (basic configuration recommendations, what the main entry points
> are, what options to look out for).
>
> As mentioned before in this thread, I don't think C-h P should give the
> same information as the manual -- be in in org-mode or rendered as
> ASCII/Unicode.  This is too much information for someone who wants to
> just wants to know what does a package "foobar" do (this is especially
> critical when package names are not self explanatory/generic, as was
> discussed a few weeks back).
>
> [... 14 lines elided]
>
> Once again I would recommend publishing guidelines and recommendations
> on good packaging practices on elpa.gnu.org, with tips and examples on
> what a good commentary section looks like.

Agreed!

I do use the Commentary for this purpose and am happy to conform with
such guidelines.

-- 
Protesilaos Stavrou
https://protesilaos.com