From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tassilo Horn Newsgroups: gmane.emacs.devel Subject: Re: [External] : Re: Convert README.org to plain text README while installing package Date: Sun, 05 Jun 2022 19:57:27 +0200 Message-ID: <87a6ar3rdw.fsf@gnu.org> References: <87leuca7v7.fsf@disroot.org> <87czfopmsd.fsf@gnu.org> <87h74ztshe.fsf@gmx.de> <871qw31ois.fsf@yahoo.com> <8735gj4ceo.fsf@gnu.org> <87sfojz63r.fsf@yahoo.com> <87h74z5nio.fsf@localhost> <87ilpf45mo.fsf@disroot.org> <87ee033w7h.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20385"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: mu4e 1.7.26; emacs 29.0.50 Cc: Akib Azmain Turja , Ihor Radchenko , Po Lu , Michael Albinus , Alan Mackenzie , Stefan Kangas , emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jun 05 20:20:03 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 1nxur4-000561-Az for ged-emacs-devel@m.gmane-mx.org; Sun, 05 Jun 2022 20:20:02 +0200 Original-Received: from localhost ([::1]:33194 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nxur3-0001v0-8o for ged-emacs-devel@m.gmane-mx.org; Sun, 05 Jun 2022 14:20:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33482) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nxuqG-0001Bl-Tc for emacs-devel@gnu.org; Sun, 05 Jun 2022 14:19:12 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:48158) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nxuqE-0000Pl-Uc; Sun, 05 Jun 2022 14:19:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:In-reply-to:Date:Subject:To:From: References; bh=kMqOVAYetXPHWdYCYn3eS9iFpm3s045bVKDnIwIO1X8=; b=FBuXxJpNlStKtV KXw3u2ox0++CskqYRrWWP9Pym8FkBBhDVabm0OJbZ6IyeZK38c3f0SSVom2WIz2Nmb5b5EbywXLU3 BvI8FJdZRDMr3yb+i/5sjriZLVBWOyct38j/c/fME7sQM1xSoJ3XmYELQ4W3x8lwnMorfRvbuDVtO XT2YdroG2GCI2xBXLmBVBzntzudH96JfZ+PFDOd9eVkvY9yJPTG+Y4Voyj2mf75DR5vkh20FPvCbP vz/xyJTQ0apKeTrMvbfZrIsL4jslXCse+X9Y0sRleQAfDd6HxXb8h7hS59gJNcsuWIEEXPE1AMIpt gJBHHPFRZoeNd5uEfETQ==; Original-Received: from auth1-smtp.messagingengine.com ([66.111.4.227]:50027) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nxuqE-0003vG-ML; Sun, 05 Jun 2022 14:19:10 -0400 Original-Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailauth.nyi.internal (Postfix) with ESMTP id 29DD527C0054; Sun, 5 Jun 2022 14:19:10 -0400 (EDT) Original-Received: from mailfrontend1 ([10.202.2.162]) by compute4.internal (MEProxy); Sun, 05 Jun 2022 14:19:10 -0400 X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvfedruddttddguddvgecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpehffgfhvfevufffjgfkgggtsehttdertddtredtnecuhfhrohhmpefvrghs shhilhhoucfjohhrnhcuoehtshguhhesghhnuhdrohhrgheqnecuggftrfgrthhtvghrnh eptdethfduieffvefhvedttdduleeigefgtdfhhefgveegtedvtefhleejueevveeinecu ffhomhgrihhnpehrvggrughmvgdrohhrghenucevlhhushhtvghrufhiiigvpedtnecurf grrhgrmhepmhgrihhlfhhrohhmpehthhhorhhnodhmvghsmhhtphgruhhthhhpvghrshho nhgrlhhithihqdekieejfeekjeekgedqieefhedvleekqdhtshguhheppehgnhhurdhorh hgsehfrghsthhmrghilhdrfhhm X-ME-Proxy: Feedback-ID: ib2b94485:Fastmail Original-Received: by mail.messagingengine.com (Postfix) with ESMTPA; Sun, 5 Jun 2022 14:19:08 -0400 (EDT) In-reply-to: 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:290743 Archived-At: Drew Adams writes: >> why can't you understand that someone thinks >> it's a good idea if the package description >> is displayed as the author intended? > > I'd say as the _user_ intends, not the author. You and me are both users and it seems we have different intentions/preferences. > Displaying a package description is for the > benefit of the user, not the author. It's > about what's most useful for users. Why do you think that a free software package author doesn't write his documentation for this very purpose? Exactly for this reason she has structured the README in sections, **emphasized the important parts**, included usage/config examples as highlighted #+BEGIN_SRC emacs-lisp (code snippets) #+END_SRC and added clickable links to [[helpful resources][https://...]]. Why is it "most useful" for users to strip away parts of that? > Best is this, I think: > > 1. Require a plain-text README, as a minimum. > 2. Allow other formats, with appropriate file > extensions (e.g. .md, .org). > > I see no reason for any limit on the kinds of > format, for #2. > > There should be, and likely are, simple ways > to generate a plain-text README from this or > that more structured format. Condition #1 > shouldn't be an obstacle to anyone, I'd think. If there is some automatic conversion like for org, the obstacle is just that I as a package author would need to commit a generated file with the danger that contributors send patches against the generated document instead of the source. Not a big deal but also not great. >> I've just tried org-exporting the vertico README.org to a plain-text >> UTF-8 version and have to confess, the result is really, really >> intriguing. So, yes, such a conversion is at least much better as the >> status quo where the org syntax is displayed literally without >> highlighting. (I almost don't perceive the org/markdown syntax when >> there's syntax highlighting but if there isn't, it looks annoying.) > > For Org, at least, that seems to confirm my > guess that such conversion's already available. Yes, indeed. I haven't seen anything like that for markdown (which is probably even more popular for READMEs than org), though. Bye, Tassilo