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 13:50:31 +0300 Message-ID: <87ilpc9288.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> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17077"; 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: emacs-devel@gnu.org To: Alan Mackenzie , Tim Cross Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jun 07 13:34:57 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 1nyXU9-000452-1Z for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 13:34:57 +0200 Original-Received: from localhost ([::1]:47848 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nyXU7-0004p6-DM for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 07:34:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43610) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyWnJ-00062b-PD for emacs-devel@gnu.org; Tue, 07 Jun 2022 06:50:41 -0400 Original-Received: from relay5-d.mail.gandi.net ([217.70.183.197]:55027) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyWnG-0002b3-Pc for emacs-devel@gnu.org; Tue, 07 Jun 2022 06:50:41 -0400 Original-Received: (Authenticated sender: public@protesilaos.com) by mail.gandi.net (Postfix) with ESMTPSA id A3B741C000B; Tue, 7 Jun 2022 10:50:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protesilaos.com; s=gm1; t=1654599034; 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=k87vVWjrFLBCMS8KfC5f6YJaWokq9uJJGCGmoNGcdII=; b=KmkQ6t62qhypGltg/aBEG582xXq7jsAYhP1jSTEtS/ZUgrY/2MKCa1KICQT5YnrL6u2akF k2y/41SLlJWHIXdGW4gNr11qN77swUAyk7p1UPPJlkoxSeWWozF4taM1f46gtIeuU6IFtL jK58TljGgeM0sL5y16N5aEG4TBy8lZ6b3L6Slm6Wtdul/QRMrb0I6IQeLvU/GXJ54v9P6k p7T53jZ+FzeZw8DTO2CaSmVKYDxl0+svKqYxIFQ95J8CFPU20rMeb3CwtL8kxCVMGzX+UH Yf14IkM+z5Zrt5JwGBmaQQCScbxboBTmjnfPdeeayTvKAaHGe1dUUtJUDHDnLg== In-Reply-To: Received-SPF: none client-ip=217.70.183.197; envelope-from=info@protesilaos.com; helo=relay5-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, 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:290847 Archived-At: Hello Alan, Tim, everyone, > From: Alan Mackenzie > Date: Mon, 06 Jun 2022 19:19:41 +0000 > >> > "It" could best be avoided by having plain text README files. > > I think we should strongly encourage package writers to include plain > text READMEs in their packages. As the author of several packages on GNU ELPA which use a README.org: 1. I agree with Alan's main point: we do not need Org in Help buffers. Neither directly nor indirectly (if we are having that discussion). 2. I write all my documentation using the .org format because it can be exported to HTML and Info, among others. 3. Org is efficient for large files as it can, for example, create persistent links/references between headings. Those are preserved in .info and .html exports. Org also has nice features, such as the ability to declare a buffer-local macro which expands into, say, "version1.2.3" or "exported on DATE" where DATE is dynamic. There are some cases where such functionality is helpful. Concerning point 2, the GNU ELPA machinery converts the Org source into an Info file. (Those who install the package can access it with C-h i.) While I handle the export process into HTML. This arrangement provides two viable options for users who (i) want to read the documentation yet (ii) do not wish to load org.el and its accoutrements. A third option, in the form of a plain README, is a useful addition, provided it is done automatically by GNU ELPA. 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. All the best, Protesilaos (or simply "Prot") -- Protesilaos Stavrou https://protesilaos.com