From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Protesilaos Stavrou Newsgroups: gmane.emacs.devel Subject: Re: Convert README.org to plain text README while installing package Date: Tue, 07 Jun 2022 15:23:33 +0300 Message-ID: <87fskg8xx6.fsf@protesilaos.com> 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> <87zgio7k3q.fsf@posteo.net> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="8163"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Notmuch/0.36 (https://notmuchmail.org) Emacs/29.0.50 (x86_64-pc-linux-gnu) Cc: Alan Mackenzie , Tim Cross , emacs-devel@gnu.org To: Philip Kaludercic Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jun 07 14:38:31 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 1nyYTf-0001t3-2s for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 14:38:31 +0200 Original-Received: from localhost ([::1]:35630 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nyYTd-0005NX-Gi for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 08:38:29 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58324) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyYFR-0000bK-OD for emacs-devel@gnu.org; Tue, 07 Jun 2022 08:23:50 -0400 Original-Received: from relay3-d.mail.gandi.net ([217.70.183.195]:54189) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyYFL-0008Bs-Fj for emacs-devel@gnu.org; Tue, 07 Jun 2022 08:23:48 -0400 Original-Received: (Authenticated sender: public@protesilaos.com) by mail.gandi.net (Postfix) with ESMTPSA id 0010C60002; Tue, 7 Jun 2022 12:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protesilaos.com; s=gm1; t=1654604616; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=b/hf0ZxSUHW9eB4f+UDyfFNsz7DJ3j+XLFDKhGYgzIk=; b=AkzrX7AfjrQAaN53kTFsxKkk0RGUP29SawjLRMQEIAlvCCUC1q/5kLuQ13xQT2hkTZ58bw XgJZrnVb8sM8SJawCP0zDqcGss6F1qxRnkKRfw/1B9Tdum11pvqcHErYFfAISKaSNAKEeF SwbDZUIB68dYu8WxKD2IfrBvhpAbs2n2WPfnjfs0XDwQmE6MlKM68MTIZb6AO8ry68AUnc Ayjhbm9sJHGsO93xD3vYDS1w+COYT9XxtzpNRJylz+IdgibuFzeWcznZ0yaiMDzNOgOdbH pWwXXCj47J256YQKtWthX46MBcYUIoVWUlUyXW5I7CDITD4cyW4vx34YS/aLhA== In-Reply-To: <87zgio7k3q.fsf@posteo.net> Received-SPF: none client-ip=217.70.183.195; envelope-from=info@protesilaos.com; helo=relay3-d.mail.gandi.net X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 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_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_NONE=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:290854 Archived-At: Hello Philip, > From: Philip Kaludercic > 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