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: Mon, 27 Jun 2022 10:04:40 +0000 Message-ID: <87h746xw07.fsf@posteo.net> 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> <87pmjnumzg.fsf@posteo.net> <877d5ut6z6.fsf@posteo.net> <87o7yink44.fsf@posteo.net> <87letjzppl.fsf@posteo.net> <87letjinbr.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="5776"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Akib Azmain Turja , Ihor Radchenko , Po Lu , Tassilo Horn , Michael Albinus , Alan Mackenzie , Stefan Kangas , emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jun 27 12:06:00 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 1o5ld2-0001FY-4o for ged-emacs-devel@m.gmane-mx.org; Mon, 27 Jun 2022 12:06:00 +0200 Original-Received: from localhost ([::1]:35456 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1o5ld1-0006z8-6G for ged-emacs-devel@m.gmane-mx.org; Mon, 27 Jun 2022 06:05:59 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36222) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o5lby-00065J-Gm for emacs-devel@gnu.org; Mon, 27 Jun 2022 06:04:54 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:45719) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o5lbu-0001HY-P4 for emacs-devel@gnu.org; Mon, 27 Jun 2022 06:04:52 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id A09CF240027 for ; Mon, 27 Jun 2022 12:04:47 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1656324287; bh=o6ZgzGWJX08A3Au1tdMpoqr+vyfch9ZBBfOYdBQUdMo=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=gekm3tZDftE79zRgIAKan5uwjvzochhOTcBSlTlTtJzoquFl/ePZcElbl6M77QHCY Top9C1xzGtz3bgZ0s0cEqbJbnx2ol75GKBMIjBnocnV4FGxdGBs0My/RKGtWLt1tSs gSUdaDh+LBmQepdLdTuqqo39xpV4fxHPVn5R83dKIZM9I45ICOBG4uqPq1GJfDEhwf 6dz1dCUI/Ay0ApBhGIP38sZ0Ew3BG4yoD1QkhYbYAHxdhxBba+veZ6WI2Aow2I2J/c wN08+BJYdit3AhfgvmYny0cCKOV5Dqjchsrb3h0yCuhXJbZcOzJ94+cXEx1lWt/yMu zXrbH2Nui3H7g== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4LWjy60SJrz6tmc; Mon, 27 Jun 2022 12:04:45 +0200 (CEST) X-Hashcash: 1:20:220627:stefan@marxist.se::w36S1X9L3EO34Jzc:000000000000000000000000000000000000000000000dd/ X-Hashcash: 1:20:220627:yantar92@gmail.com::xgNTKecU4RiKAgBI:00000000000000000000000000000000000000000001oiC X-Hashcash: 1:20:220627:akib@disroot.org::suZCpS92932zd6Rw:01pY1 X-Hashcash: 1:20:220627:michael.albinus@gmx.de::37D7diAx7yTpIqhA:0000000000000000000000000000000000000001n73 X-Hashcash: 1:20:220627:luangruo@yahoo.com::aAeL1csrUyv9ma5T:00000000000000000000000000000000000000000001J7J X-Hashcash: 1:20:220627:tsdh@gnu.org::PyZpETOxrHAyGEHT:000003dVy X-Hashcash: 1:20:220627:monnier@iro.umontreal.ca::eqdxoav8UKGsn8AV:000000000000000000000000000000000000051Pf X-Hashcash: 1:20:220627:acm@muc.de::c9/JXThT7Hp/wzCA:00000006ZTt X-Hashcash: 1:20:220627:emacs-devel@gnu.org::npLxnYmm60JK9LUc:0000000000000000000000000000000000000000006RPz 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: (Stefan Monnier's message of "Sun, 26 Jun 2022 11:23:41 -0400") Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.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, 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:291654 Archived-At: Stefan Monnier writes: >>> FWIW I find this particular conversion made things overall worse :-( >> Hmm, what in particular? > > I didn't like the two spaces after the "bullets" and more importantly > the information about what is a title was completely lost. > >> As I said it doesn't have to be this specific formatting. > > Sure, I just mentioned it because I found it rather odd to return > a worse result than the identity function. My example was a pretty clean markdown file, which is usually readable enough in its own right, so most post-processing doesn't help. But I agree, it isn't as easy as just using pandoc's "plain" output. >> It could also just be cleaned up markdown, moving links below >> paragraphs, wrapping lines and stuff like that. > > Then again, this can (should?) be applied to the source directly. As in sending upstream patches? From my experience a lot of maintainers (regrettably) prefer something that renders well on sites like GitHub or GitLab than that is readable as plain text. Or do you mean writing custom code to process markdown files? > Don't get me wrong: I'm definitely not opposed to rendering Markdown to > plain text. I've seen a fair bit of "GFM" files that are not great to > read as plain text, so there is clearly room for improvement. > Maybe throwing out the badges would be a good first step ;-) Then again, this ties into the README files that look better when rendered on GitHub/Lab, and where it is worth considering if *not* using them would be of more use. If this is about providing a good overview when using C-h P, using a good commentary section (that does not include comments on how to install the package, contribution guidelines, screenshots, etc.) might be better to begin with. This is also related to the point I had raised earlier in the thread that when a package generates a manual from a Org README, using the same file as a README file results in too much (redundant) information. > Stefan