[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.
Agreed!
I do use the Commentary for this purpose and am happy to conform with
such guidelines.
--
Protesilaos Stavrou
https://protesilaos.com
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), (continued)
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Ihor Radchenko, 2022/06/08
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Stefan Kangas, 2022/06/08
- Re: Org mode and Emacs, Stefan Monnier, 2022/06/08
- Re: Org mode and Emacs, Ihor Radchenko, 2022/06/08
- Re: Org mode and Emacs, Richard Stallman, 2022/06/12
- Re: Convert README.org to plain text README while installing package, Tim Cross, 2022/06/07
- Re: Convert README.org to plain text README while installing package, chad, 2022/06/08
- Re: Convert README.org to plain text README while installing package, Alan Mackenzie, 2022/06/06
- Re: Convert README.org to plain text README while installing package, Protesilaos Stavrou, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Philip Kaludercic, 2022/06/07
- Re: Convert README.org to plain text README while installing package,
Protesilaos Stavrou <=
- Re: Convert README.org to plain text README while installing package, Stefan Monnier, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/06
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/08
- Re: Convert README.org to plain text README while installing package, Michael Albinus, 2022/06/06
- Re: Convert README.org to plain text README while installing package, Jean Louis, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Tim Cross, 2022/06/08