[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Philip Kaludercic
Subject: Re: Convert README.org to plain text README while installing package
Date: Tue, 07 Jun 2022 12:07:21 +0000

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]