From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: [External] : Re: Convert README.org to plain text README while installing package Date: Mon, 6 Jun 2022 00:23:59 +0000 Message-ID: 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> <87a6ar3rdw.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5660"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Akib Azmain Turja , Ihor Radchenko , Po Lu , Michael Albinus , Alan Mackenzie , Stefan Kangas , "emacs-devel@gnu.org" To: Tassilo Horn Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jun 06 02:25: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 1ny0ZA-0001IA-UH for ged-emacs-devel@m.gmane-mx.org; Mon, 06 Jun 2022 02:25:57 +0200 Original-Received: from localhost ([::1]:57582 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ny0Z9-0001eG-DI for ged-emacs-devel@m.gmane-mx.org; Sun, 05 Jun 2022 20:25:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39696) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ny0XY-0000nC-T2 for emacs-devel@gnu.org; Sun, 05 Jun 2022 20:24:16 -0400 Original-Received: from mx0a-00069f02.pphosted.com ([205.220.165.32]:42096) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ny0XV-0005Di-EM; Sun, 05 Jun 2022 20:24:16 -0400 Original-Received: from pps.filterd (m0246627.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.5/8.17.1.5) with ESMTP id 255MIZcj026895; Mon, 6 Jun 2022 00:24:03 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2021-07-09; bh=VBVK9+ME6SAB/hbdUFcEhNdV7dbc+bFrOhSNeh96GOM=; b=icSG+J7F6qTpnrVCt9xZnZ9ZkBjnXwVSwTX+hH74gyUDTYToe4Bd875W9a9SX/AOuuYP InFOg1XligoeHVdiQ6PQZN7cbMKi9TQRwU7JZOFTUxHFUuA2cugSuJkd0lkKK2hHlQgB fhE6dZKE856X+CiB3OKn63Xqq/nvnBEuEDmGtIEJ63S5od3COX6ZycpHyrWt5w5/nyJb mIIAR2Dtr7MCmstKpFgmIvkloFjdmeEBdW7m+D8+WO1G7tuSzl5UVS6pU63sQKIyF5lz yVf2sCYjkhuXGPOd6LQFecvzhH4g5y0guWUPcXwTCHO+vyQgfX7RBE09+2EP90W/U5dO CA== Original-Received: from phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta03.appoci.oracle.com [138.1.37.129]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3gfydqhupn-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 06 Jun 2022 00:24:02 +0000 Original-Received: from pps.filterd (phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (8.16.1.2/8.16.1.2) with SMTP id 2560AAPW029713; Mon, 6 Jun 2022 00:24:01 GMT Original-Received: from nam10-mw2-obe.outbound.protection.outlook.com (mail-mw2nam10lp2109.outbound.protection.outlook.com [104.47.55.109]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com with ESMTP id 3gfwu1fby8-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 06 Jun 2022 00:24:01 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=K8rsDIIgtqlgagwF7NPHcRbaUUUCIzm81UoocXbRiuhLSi5hrLMiRO9WpIMiZecnIX18J2lBa1exId2NTIxBMEtrUgwDjjBkFTA7ja842DCz4e+OX647yQmdqhchFoeRJcM13/g3Zf7vkjGNxcUIRoj+0lg+hDCmRjcZHzvvJEl5o9f5RlntEJL5R6urnFnVV6/0bOhZRjJs8Ov1iQtGm4Dz8mYqQIPhDaiONMD+SpcrOQ5jejHi4kgMr8QXHGAK5jvreKvA9XF3UelKbi7AB8mWOgTVk62sTh7kSC/mUKFKIW90eOzQNwVuD74YbQJ5DhQwFznhgk0s9EviQAo57w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=VBVK9+ME6SAB/hbdUFcEhNdV7dbc+bFrOhSNeh96GOM=; b=bw67pN4tJVA+O5UE+P4olBSl8Aj4qKyXqP667xFwWF6H5fFXKm5HGS/+jGSLGrWJhSMUKdFWTjZ+o2Xpl0mv1H01ACLm+owxXRaOj7b3aEU4GTbBey6nhbk3vUIhyPdBIqi+tpuklTg+Mzm9GDZdGUWWGN2TykgBkEmoMIInQLwPwsroTPGYO3E8gTCT15qmWMr4YHhCVtvClFO7JTRvqCnOjBq7UImJKhByHPUZFR0zUXsrRpaYgNQ/B+qhh+E6XzRIRSdQX4SoSNiCPJD6xcSJMTnptL22pStdziMN859J1xKc9104FmHXT1pHEYlcPm052/TFlbHxAieesPe0OA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=VBVK9+ME6SAB/hbdUFcEhNdV7dbc+bFrOhSNeh96GOM=; b=WZLYip3hRwYhqQc2l3EKXWoXBDiTaVpMoz+q+Usa71722U49NwobBpRDza30UEdQCEfNc4ieUUdhPO/YXvoHtA2SC3dQGmVmSUYxOGGqrRSRCAgR1W9CLE/lGvKsmb9sAiZ+f38GpXqRjgbp87bS3vnXD9ERbjO+yp7pCVDzaIM= Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com (2603:10b6:a03:37e::19) by BL3PR10MB6018.namprd10.prod.outlook.com (2603:10b6:208:3b1::11) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5314.19; Mon, 6 Jun 2022 00:23:59 +0000 Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::818c:10bf:c1b5:e224]) by SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::818c:10bf:c1b5:e224%3]) with mapi id 15.20.5314.018; Mon, 6 Jun 2022 00:23:59 +0000 Thread-Topic: [External] : Re: Convert README.org to plain text README while installing package Thread-Index: AQHYeQW39h1fPduOME6551JRqZ2Y761BbWNQ In-Reply-To: <87a6ar3rdw.fsf@gnu.org> Accept-Language: en-US Content-Language: en-US x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 60911d33-001b-46fd-849d-08da4752d9bf x-ms-traffictypediagnostic: BL3PR10MB6018:EE_ x-microsoft-antispam-prvs: x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: TS7AtSlhGgxmNGFh7npHG1YZITMnXNv0kyJsG9MC1bWSY3MDubzNRS3kmhyszWfwFoRkKKLuyWsiZfSV2arAqh7rBPPDM2f04pnJ7mrL24yvd2j/v61mUirNQKxyQSBTT7qdVqVAeiYdT7abtNE8tbX/f9IxC4qSgTs0KkNmEwpoUOix6TiZ6Pkqo4zqrr4up8vz7txZYFdAMI97NzAO6Uistm4YpdcSrihOdwb8cU+IKhcnDUuNEVZRBR2XqczYTXthGt0FWDHqQkMDnyj8RoL5cqzd5rFSRj/gu9XeWDZbZXc6BrtvEnT9RKJNCMvJbp0m8MPERGnr+pdq0ahfbOFYuLHU3OoV6C/lqWoR1Gfg6BmW+qf6IO8wEQi0jzUuHJ/GykNPHP4At+8AjsdupFytgNhLk5nnMnyVCAHRo6zUVjSjSosiHM/M+B/1f33nuJTKUEZJzA4r13u7/Ra/R6beH/KQdBTj0SG9d0g+iJw7LNhx/UsjudpOCjZetjJiY/6l8fU43KeYErGuwzIMgKa75FH4Qo6PXh4E4TBwJJWAB2lPShDyinvQS9cmHEDWUrT2dafr80+9RZayfJBSWwx+TZUYCV2lrKbjkCBGEmysM1b00BTsRKtvSe8so4HcUW2uD7OP0i/YOaEifWOqHzJlCFbg5P6Yx2rYyr+xEyb4NF8uP3StuK8Lmk6EJRo67Rv8DYpNl7EfB8ak7K7+a5Xm3rWKMAtCqDCA1ImBDEE= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SJ0PR10MB5488.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230001)(366004)(316002)(6916009)(54906003)(122000001)(38070700005)(64756008)(86362001)(66446008)(66476007)(76116006)(66556008)(4326008)(33656002)(66946007)(8676002)(186003)(44832011)(71200400001)(7696005)(6506007)(2906002)(9686003)(26005)(508600001)(38100700002)(5660300002)(83380400001)(55016003)(8936002)(52536014)(2004002); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?f9XaZYRa9vVUDmKPV3+fN4OwjfiZ1/Fl26KXDRJR3Iu30fo24VWOXT+gzQBq?= =?us-ascii?Q?SYr6lY6ChrJuNlxcdafU/7QWOVcmggQThLJhVdaBrSQ9Rvgns9j06uz3UNfo?= =?us-ascii?Q?E1eq4yLlK7cOoO+GsPts5j8yomAPd8oTBLL0TKTt1vbzTXHjdteHLYnbqm/i?= =?us-ascii?Q?OSF0gxuHGVMnHKa3OjQmJLQQyB/hsUubzmIB0J0XonarqY+nUv0BfEvVQcTo?= =?us-ascii?Q?0vZ6xnjAhmKpuGAT14SAMMGCU67q+nzW0dF9U3sba0lqoReqLf3LAJPDhUEk?= =?us-ascii?Q?MYUifqUNwCaluDci21xlUaSHW7sGahNUWq2fVH9SJX3MBzSZ4xw6QJBOQQXl?= =?us-ascii?Q?f9fvV8lBmv8qAUf+AWa5Zriz80QXESRDcuN1kC+Fs8ksMK6lHWf4UswY5Gfv?= =?us-ascii?Q?VBWt/C0HopI5beSELspW/Mo+I5zSjepI186Y2OqBJ7J7x1VwmvUXe3MOwQcb?= =?us-ascii?Q?yQtj0FSOmY1cXH+UyMRPAGuy7m71MwA4i/FpdmxP4BY38D8ZTzp8TcYs/eQd?= =?us-ascii?Q?slKRRmZe08GzLwc4IVkRxTpn+4WoHAUhnTZokNJyB4TuvnctOShmc0l5MIle?= =?us-ascii?Q?nRjxXrkdgnb/da6bgjMmcvCkgBYXUe8qsIx7RDOuHGHUGktmT96k90elhO3t?= =?us-ascii?Q?rs X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SJ0PR10MB5488.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 60911d33-001b-46fd-849d-08da4752d9bf X-MS-Exchange-CrossTenant-originalarrivaltime: 06 Jun 2022 00:23:59.1961 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: jd+BNklRrln+j1QpCRCw9Bl6dtdtFqyGQACxdwl50TFvaf8KJ8uwZfpEGab9wSOEkUpO1lFOt9k/CyACH0bd1g== X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL3PR10MB6018 X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.517, 18.0.874 definitions=2022-06-05_12:2022-06-02, 2022-06-05 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 mlxscore=0 bulkscore=0 malwarescore=0 phishscore=0 adultscore=0 suspectscore=0 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2204290000 definitions=main-2206050114 X-Proofpoint-GUID: hziGM6_7YnwcurXqLQ8Xv1U0zh6Z63gh X-Proofpoint-ORIG-GUID: hziGM6_7YnwcurXqLQ8Xv1U0zh6Z63gh Received-SPF: pass client-ip=205.220.165.32; envelope-from=drew.adams@oracle.com; helo=mx0a-00069f02.pphosted.com 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_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:290753 Archived-At: All I meant there was that it's good if a package description is written from a user point of view - what it does for users, not just what the author intended in writing the package. The motivation and design underlying the package are important, and _can_ be useful to document (for users and others). But most useful is what you can do with it as a user. > > Displaying a package description is for the > > benefit of the user, not the author. It's > > about what's most useful for users. >=20 > Why do you think that a free software package author > doesn't write his documentation for this very purpose? I didn't presume anything about how or why every pkg author writes their pkg doc. I assume that most do try to provide useful doc for users. My point was only that the description should be useful to users. Whether the description "is displayed as the author intended" is, on the other hand, essentially a nice-to-have. (And I, as one user, really like to have it.) And I was clear that authors should be able to provide whatever display format/method they like. But I think _also_ providing a plain-text description of some sort (a plain README) should be a minimal requirement - at least something that's requested with "Please at least provide a plain-text README." > Exactly for this reason she has > structured the README in sections, **emphasized > the important parts**, included usage/config > examples as highlighted Absolutely nothing wrong with that - quite the contrary. That's to be hoped for, even expected. No one said anything to the contrary. > and added clickable links to [[helpful > resources][https://...]]. No one said that authors shouldn't be able to provide helpful links, images, and other artifacts. Even flashes and fireworks, if they like. > Why is it "most useful" for users to strip > away parts of that? No one said that that's the case. Not I, at least. Are you looking for a straw man? All I suggested was that authors should, at a minimum, provide a simple, plain-text file README. I explicitly even said that (IMO) that file need not say the same thing as whatever their other, formatted README.* files say. Why is a plain-text README desirable - useful for everyone? Because it requires minimal paraphernalia to easily read it or otherwise process it. Lowest common denominator. This should be a no-brainer, I think. > > 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. >=20 > 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. As you say, neither a big deal, nor a great obstacle. =20 > > For Org, at least, that seems to confirm my > > guess that such conversion's already available. >=20 > Yes, indeed. I haven't seen anything like that for > markdown (which is probably even more popular for > READMEs than org), though. Even producing a plain-text version by manual editing is likely not a big deal in most cases. That's my guess, at least.