[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: Protesilaos Stavrou
Subject: Re: Convert README.org to plain text README while installing package
Date: Tue, 07 Jun 2022 15:23:33 +0300
User-agent: Notmuch/0.36 (https://notmuchmail.org) Emacs/29.0.50 (x86_64-pc-linux-gnu)

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.


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

Protesilaos Stavrou

reply via email to

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