From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: Convert README.org to plain text README while installing package Date: Tue, 07 Jun 2022 12:07:21 +0000 Message-ID: <87zgio7k3q.fsf@posteo.net> References: <87h74ztshe.fsf@gmx.de> <871qw31ois.fsf@yahoo.com> <8735gj4ceo.fsf@gnu.org> <87ee038ipt.fsf@gmx.de> <87o7z61v59.fsf@gmail.com> <87bkv527p5.fsf@gmail.com> <87ilpc9288.fsf@protesilaos.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10991"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Alan Mackenzie , Tim Cross , emacs-devel@gnu.org To: Protesilaos Stavrou Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jun 07 14:19:42 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nyYBS-0002c2-Rs for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 14:19:42 +0200 Original-Received: from localhost ([::1]:38874 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nyYBR-0004ec-7x for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 08:19:41 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51932) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyXzb-0002Jg-Rw for emacs-devel@gnu.org; Tue, 07 Jun 2022 08:07:27 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]:50493) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyXzZ-0004UA-71 for emacs-devel@gnu.org; Tue, 07 Jun 2022 08:07:27 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 5490424010C for ; Tue, 7 Jun 2022 14:07:22 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1654603642; bh=4RxKT/VcGtY+t2JgxJnslXgP66AALI3MiFK5A0mjqcA=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=PtqFKHYi4eQFOmQ50Z6PgiIQ5zIqBnX648Rr9UzSvsJT+S6gBoN/dwXShil0qNOU/ 3CJ0TO+m5N64qd5kmQpD26wsJCea7J0+SmxO87rEQjwnklkugNtFJ5Ab/5oZB1SfOl BX95zwF5fUR/DQ8gjNRneoGgL3L70JrIsKIfMryUhRoRIdFoqUXsgtROdnY3K9JCGO HnLoHFN9FQ8tdKbIOs/G98heSEaOHLMqIkTgJZa6S46HQaJngRAUYN3fMqFsn1LBU6 dYtMJnElhPcORJ4CuQjihfr9DG4XHJ/8kb8urtUQi6hUo9o6Sgz8DhSv4AOmwXC0B1 BPcds8kOfyUiA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4LHTcn47h8z6tm6; Tue, 7 Jun 2022 14:07:21 +0200 (CEST) X-Hashcash: 1:20:220607:theophilusx@gmail.com::78GTFibrwVUu3ZP1:00000000000000000000000000000000000000000qAK X-Hashcash: 1:20:220607:info@protesilaos.com::GfXJyN2KKKRfmXNU:000000000000000000000000000000000000000000yzr X-Hashcash: 1:20:220607:emacs-devel@gnu.org::yVpVAPhjPFwuHqh1:00000000000000000000000000000000000000000010X6 X-Hashcash: 1:20:220607:acm@muc.de::vhWvpcn/col9Wzxa:0000000386j Autocrypt: addr=philipk@posteo.net; prefer-encrypt=nopreference; keydata= mDMEYHHqUhYJKwYBBAHaRw8BAQdAp3GdmYJ6tm5McweY6dEvIYIiry+Oz9rU4MH6NHWK0Ee0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiQBBMWCAA4FiEEDM2H44ZoPt9Ms0eHtVrAHPRh1FwFAmBx6lICGwMFCwkIBwIGFQoJ CAsCBBYCAwECHgECF4AACgkQtVrAHPRh1FyTkgEAjlbGPxFchvMbxzAES3r8QLuZgCxeAXunM9gh io0ePtUBALVhh9G6wIoZhl0gUCbQpoN/UJHI08Gm1qDob5zDxnIHuDgEYHHqUhIKKwYBBAGXVQEF AQEHQNcRB+MUimTMqoxxMMUERpOR+Q4b1KgncDZkhrO2ql1tAwEIB4h4BBgWCAAgFiEEDM2H44Zo Pt9Ms0eHtVrAHPRh1FwFAmBx6lICGwwACgkQtVrAHPRh1Fw1JwD/Qo7kvtib8jy7puyWrSv0MeTS g8qIxgoRWJE/KKdkCLEA/jb9b9/g8nnX+UcwHf/4VfKsjExlnND3FrBviXUW6NcB In-Reply-To: <87ilpc9288.fsf@protesilaos.com> (Protesilaos Stavrou's message of "Tue, 07 Jun 2022 13:50:31 +0300") Received-SPF: pass client-ip=185.67.36.66; envelope-from=philipk@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:290852 Archived-At: Hi Prot, Protesilaos Stavrou 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.