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

[Philip Kaludercic <philipk@posteo.net>]

Hi Prot,

Protesilaos Stavrou <info@protesilaos.com> writes:

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

So it might make sense to instruct the ELPA build system to not use
README files, and instead just rely on the commentary section of the
main file.  If you check out the elpaa--get-README function
elpa-admin.el, you'll already see that "README.md" files are commented
out, because

        ;; Most README.md files seem to be
        ;; currently worse than the Commentary:
        ;; section :-(

which is indicative of a general problem, of how README files are used
since GitHub (I have commented previously on the issue in this thread
https://news.ycombinator.com/item?id=30336703).

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.