From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,HTML_MESSAGE,MAILING_LIST_MULTI,PDS_OTHER_BAD_TLD, RCVD_IN_DNSWL_MED,T_SCC_BODY_TEXT_LINE,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 12716 invoked from network); 19 May 2022 15:11:28 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 19 May 2022 15:11:28 -0000 ARC-Seal: i=2; cv=pass; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1652973088; b=exHbVrmS1N3ncNuAXFUYTH/FRRNNbJt9ldx8389VMiEy7ctV+/yF//5BMeNJHvZYhCQDQWIIR8 rx25+v47go3rAkLGAEYZhkVVmaID4H3JEkQB0Tx76DhP/ZgQ5eUhfbOh4pJRTRsT3rVD2shREl gjMKH0zSFLtnPBDuSWu9bAv8aXBMM+pJjTLfahMaoGUpqwRrEPASaXDD7HReO0cb34fJ5bVpMV SRwN1uLlVGAeyLOs1RVrvDCyjeqLUim665YJZvOGyRY5MMEuuxDvrlVJRUGNt5eFv5ZwS/7W8w cMdztRvJHmh8vS/gcCwCpUsgGRMmEld3VD/BvVsWaf5sVg==; ARC-Authentication-Results: i=2; zsh.org; iprev=pass (mail-ma1ind01on2040.outbound.protection.outlook.com) smtp.remote-ip=40.107.138.40; dkim=pass header.d=iisc.ac.in header.s=selector2 header.a=rsa-sha256; dmarc=pass header.from=iisc.ac.in; arc=pass (i=1) header.s=arcselector9901 arc.oldest-pass=1 smtp.remote-ip=40.107.138.40 ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1652973088; bh=+DMMT1MWBlHpOwegYW83utMJkBbEl1oqQ/ksxVQq+0Y=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:MIME-Version:Content-Type:In-Reply-To:References:Message-ID: Date:Subject:To:From:DKIM-Signature:DKIM-Signature; b=LOrRONs+nRzGOBJz+cZqlZJ2jJrztyT105k4MkRe+uNYLPxRJ+2TPi+o74DKuVWt2+PVED3xHP Tik9Bfi2eEM6CporxHlFbZ+cQDX2COB8JmDNy75k6Mdma+3S4aIncwxyGlZkor6lcA9/NowjmO KF8Rv6krMlRRsc0b88nopvFEkAtEfHDIGbWDnUocEZ0UD1ix+jSN0FzflMHF8OhvglwQ8Pcahk 4iiA+/jjP5rWaVedXbwjQ6DjAStYxEcBlEIxJUuuKgeAHyu15pbfNUMYnKutyrg2364hQdatLE t1Dh11tu++tMNgkp6STs8VK2f0HEEKR7HyrGAcEgvvAxuQ==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20210803; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:MIME-Version:Content-Type:In-Reply-To :References:Message-ID:Date:Subject:To:From:Reply-To:Cc: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=d7skAGkHll3hTN4NZ2/H4Owg6GYVIjSjXD54YdO0cvs=; b=pqE6Q3Gb5lV0wPxCL9RCW61tNo IyQ5/ufsvkz8sq1YGULELCuVpnT05iT0phuk66uVjtFLkKs7yGR5glCoPaXQKCIzAm6XbKODEofNP nSy9YuxnK6snYJlFTjQqKnozt5RY1wzT/ZggS2f46msvcx4eWH7wSNNWxVijHkHfgAOnT48A7UBYT c0ezgAK250nfYP1kliOUav/i8yZ1UH6mFzywmnCgwum/ekwn0Ynhwi2dPFxXJow4OhwR7985CPj01 4bUIBSEGVBIrVRRA/prhjy0lzcCf+ZXWEe5aQN5a/m91p+EKdbAhpO3lNCZRJhf4uchrVS3PmdSYQ eCn5aWPQ==; Received: from authenticated user by zero.zsh.org with local id 1nrhoG-000Cei-4v; Thu, 19 May 2022 15:11:28 +0000 Authentication-Results: zsh.org; iprev=pass (mail-ma1ind01on2040.outbound.protection.outlook.com) smtp.remote-ip=40.107.138.40; dkim=pass header.d=iisc.ac.in header.s=selector2 header.a=rsa-sha256; dmarc=pass header.from=iisc.ac.in; arc=pass (i=1) header.s=arcselector9901 arc.oldest-pass=1 smtp.remote-ip=40.107.138.40 Received: from mail-ma1ind01on2040.outbound.protection.outlook.com ([40.107.138.40]:19170 helo=IND01-MA1-obe.outbound.protection.outlook.com) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) id 1nrhnf-000CIx-Ri; Thu, 19 May 2022 15:10:53 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=U50nfyhwXvFQUdU2pCaJXG4hSpON3Fv6C53ihVAyxZdCQ72ssmaJDebWqfg45R6m3FlHg74XcxZK/irG8YNnmo/geYal1UzR5VJg/uxJdiXDZ/fo9EFTZKTbbYlLeKE1Ks4edCWwP/AcpO13ouxNZPhtrckmQf7WREO6pOYrbh/qzdnHnUeyDOcTbNIdgYVdL6Tf2KzaGBGmPctjSIVWtHDI3Y9iWZRHAfoo9HK68eP/plPhZO5QBNbEHrFRqI7nt5aEc614vXhzq0xWwOdoLJ/ASTZZOp8UWliVZL/V0pJoiFpZ8vCAWH+mOJPU6Lx4IZG7sVOOTsNmc1xHd+FdqA== 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=d7skAGkHll3hTN4NZ2/H4Owg6GYVIjSjXD54YdO0cvs=; b=JyPHFxtUiJuUYxsBJ8xKk4JaymlMpYHX8l2i3Js8QiQlvCUe/O/lZ+rUN34kPVPvaYbu7qKe0dsuMAQLLJ3GND1VUK+jSoENDFIDBZ43+53OCWFOFyblpFNvFVmnGDWjQENd2SVrwfUikR8xMD8bmfxjysIO6cDqU4fuNjYgoWAuA7tjk9uI/ZJpWq0MrVIOlyjF1DuWDiSf6SAW4eNa99XNzA/B0ZJC2M+wJ/XIZ2jRJ+ln0xUAlSluNLtjBDjdMvsTS4dlxD7+SIzmyS5Az/HB7bUG6gJw6FKelYcCmPvMs/FKa1IUSfCFC60k4VDuBgUBgduq4fxQrJTfG4EwJw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=iisc.ac.in; dmarc=pass action=none header.from=iisc.ac.in; dkim=pass header.d=iisc.ac.in; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iisc.ac.in; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=d7skAGkHll3hTN4NZ2/H4Owg6GYVIjSjXD54YdO0cvs=; b=M0LEqqAOkNwSa7PBFsK/uCV3jOdUbMKCu7ulWhqR5s0mZSHyfCLZgzVUGnaPY7GfVbbnnUBKP1Ydx17/vTstJXX9OPZAhRxmKw9dHqgo5HSs5zEySkuo9D0zYuMaofbYGIY3nDdHs7Yk6Ac/K+1RbYfWi7zQKxHiICtgWZABnnQ= Received: from MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM (2603:1096:a00:57::20) by MA0PR01MB7380.INDPRD01.PROD.OUTLOOK.COM (2603:1096:a01:3b::7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5273.15; Thu, 19 May 2022 15:10:48 +0000 Received: from MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM ([fe80::c5c8:a6e0:2dcc:94bf]) by MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM ([fe80::c5c8:a6e0:2dcc:94bf%5]) with mapi id 15.20.5250.019; Thu, 19 May 2022 15:10:47 +0000 From: Bevan Stanely To: Peter Stephenson , "zsh-workers@zsh.org" Subject: Re: Proposal: Use Markdown syntax for README and other documentation Thread-Topic: Proposal: Use Markdown syntax for README and other documentation Thread-Index: AQHYaswvrDc5gotHKk2fQmCGrdWamq0lZLoAgAAwMYCAAAbYgIAAGk72gAAwqgCAAGSfoA== Date: Thu, 19 May 2022 15:10:47 +0000 Message-ID: References: <33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com> <1540829696.208973.1652950518801@mail2.virginmedia.com> In-Reply-To: <1540829696.208973.1652950518801@mail2.virginmedia.com> Accept-Language: en-IN, en-US Content-Language: en-IN X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=iisc.ac.in; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 2c2c804f-6039-4d85-2e5f-08da39a9c0ff x-ms-traffictypediagnostic: MA0PR01MB7380: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: RDB+uhHzjriV8UVv+LdNtQT5eWvfWDWzsgwvKyd6mDtTkK0NQLHZDxBWgYh/zkkvh1fczO8quPscDte/3mzkmGOP3WbwtlOpj3/8eYZnnEjKcphVy3Ih5AR3Jcdd9aOzTaxuqHPSdhyXM3z3IHwByOTbQvdOpiYlsmFnlb/08zf5l2HgtjHokB5Igdg4kc5tpZGL4kzExlOSmqdXhgG9gA8t/wBrqG+F/W/poE4OtvYjKNhty0vGQDdd2HoLl0YdfFAe81BHjqpr3bq/75U1Nkc481N2QK34Dxw+VMZU/DHCPanKfl6bGCty7MomrFkoq+E/aUYtR8PE5Ku7BBTXwAsNrv3y31YfdqwFemmsurPgQv3bVwOHp5o653VwZEIAxmYVfdlEXevPMzE7S/P/3B+2A1zqg5+GVrvRYA5NRnQbIINUC6xy14RmuPqHOhGaFvGQ5cgKFpyYBpkxoA4SanSOO+RkBVdXlclXfJRSG7KceX4S8sGmZ9J1qOMR5/QDlEQ0hFDOEOjILpZQaaUr5kb3ERfJlOUYyg5AvlaRtbL2Ic+9iWxnZ8Ssr7WVIJmtUby9W/+p75h1FVrRwWdwKOigu7ikcE1X1g+wCvtgPI4uEJBXLOEv+QrsjKWiitM0+6Fxqacr7h41O+gdXXxK6MOX9fFaZLy0C1rXFIReNaYERk/taDwOwAZRQ2emQeAJa3qEL8quvfKYc0ZUnD961la/Xsodfi6xWMXLD5vWZwmy/xU1CZf2nsyFerKYvW9HQI9+o+Q0rl3sqDJJqO5eYmt2JnHxbD/gRQsXs8korC8= x-forefront-antispam-report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM;PTR:;CAT:NONE;SFS:(13230001)(4636009)(366004)(38100700002)(316002)(26005)(6506007)(9686003)(786003)(110136005)(83380400001)(53546011)(86362001)(52536014)(8676002)(7696005)(5660300002)(166002)(64756008)(38070700005)(2906002)(66476007)(76116006)(66946007)(8936002)(66556008)(71200400001)(122000001)(186003)(66446008)(91956017)(33656002)(508600001)(55016003);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?hVUDRDaf9VU8vxumP0gzNZrqL+eKHeqQvGEHQF3N1P1lpAguel8vpAtmeRvU?= =?us-ascii?Q?RMGZ3Dv9gTvggcX1cn/XuNgqwPffAQHVHicbgyLx8QsJtdvDnDeLuGyu8Z7u?= =?us-ascii?Q?ZyvyL2y710FGcbAMnaYd5ITDt9sV/Gf5yCHetRWWefCqdZwf6SUnLI6K4i8r?= =?us-ascii?Q?BRyQNjHIyeXM/N0kiVtkYpN+1LskkEXe+QL3fJ8p5eymeC7JIgL6xwKItLtN?= =?us-ascii?Q?rIz/s/mZDmWnU+eue5IKNl4tLWF47gI+xhz1zo7TTVX4PP+k+wAoqMfynGT+?= =?us-ascii?Q?LWWXG/HSr4jiW2oAGt2Bj8vEDbthwdCJPhFu7MnHMf/P+yPdFCBkCVuEHfqP?= =?us-ascii?Q?xPCFAl4vrE87cZiRPydJjmjcAwMtcy+RE8c2gKUTjBaPUd6r4lbE85WO3BXH?= =?us-ascii?Q?WbWNb213ICPvVsCZ/CR6koSxLk4QG8lVz7gHIZ4GN7be4y6WiFvuw8YJwV4A?= =?us-ascii?Q?eLJ6CbOaZKD5krYmEi1tB9WcbavLod2ig9G/GqrgrVbctCdZS0sDV7xaQIg2?= =?us-ascii?Q?4oDwusdN5CttyEjNdXQL8TMyjEv1/4ooTlGmnZsWsTL/N7HaeAIKV2/Telah?= =?us-ascii?Q?YywbJvOzT38lOWnqbHHLMd9Ml0sKMKEuMMDHEZtciK0pJORdkzwd5+GCxgd/?= =?us-ascii?Q?mHrU5kBBj5PiC8yD2Wu3WzWShbtKpaaeEG54vWao/pDCsihlmNILBMauTMq9?= =?us-ascii?Q?9q+x3fyBwbBWMi2tWXvjHMhsQLVX2s4hEVrvb88nldSSA9gYfUdsitTESpMo?= =?us-ascii?Q?A1H2EcodPowLGDiFCXM8xjMZjlS4ezNC33NjFlWFV3PAseSfvKDh7W70z9Iy?= =?us-ascii?Q?nEPV0/SlSiMKKDjKe7T7nA7vg3qE2IZOcdOhVxAVomCtZlkk8RVk0Hwpfsfe?= =?us-ascii?Q?mXyfZWXoqzD/tNJtplmSQTK7wG0vTkX6z62nrUfBJ/KLLzq/DoE0zNKGCLTo?= =?us-ascii?Q?3ZOhNkMSWctE8K4u3UeZEn1qGltpys/cZEZZMyvAqayy3guL6o4jZSsw6vqL?= =?us-ascii?Q?pWOb473YCk7NCdCWo0c0ILiUqi4eZKQrUxuWv2O7+Iwh1c8g6q3l1jUqrGHm?= =?us-ascii?Q?QGryL9LUo4b54bPh7OI/dg2VEYD6JYLV0GEZa2GffxWiTxzZITRtkA2O77sC?= =?us-ascii?Q?V0FEkFn71h5s7InZEq0qCew0oJJD7Esd2RIkfAnQMNz0FNQpo2WuozlTKu0x?= =?us-ascii?Q?9c/5QNSp6/7dL6n23nVyiKx2ILvJegs3fWpVXzi4LpmT6B5v5C5kVpFYQtv9?= =?us-ascii?Q?kRXJrvcEhoyKPP4zNHKomqwWXOVfIKyXXrgUC5BrbBrQnaFz8988Zn5mdqcb?= =?us-ascii?Q?TZAn5F16WHUPZcn/qXN804TweFr3AgI9/g5tuea1tuqBaVJzJy8pU50B9/JM?= =?us-ascii?Q?2MFi+AFjJ5v/fnJwJzfRxplZleA7VMp/G55MkxiVl9yUOIV1HKYgwLln4WI1?= =?us-ascii?Q?mLoFajmsKKpzeQEpPWN4TeivmAGzMCZceyOBpMp/USl3aY7T3WMIWxlg3obZ?= =?us-ascii?Q?wJ1RaAkCQYLUAtWB5hc8Kl1AbAiAbj9cKOs2JiIMp8a3Xh+LjQW+dPWz1gzo?= =?us-ascii?Q?Hvs0eyKQkcuk52FNQPfoU9zzO4HlAM8spLtV3mA1M2eIBJ9m873RSpCDyQ/t?= =?us-ascii?Q?CJw0FUqReY1JVh/QpR795MIaViMNMzgtH3oHC4X0iBXYVXgJM+JWHaUazKyb?= =?us-ascii?Q?rMz+6loxdFZT2mjLNSDfOWlOFEwuhNj+6Dp6HbjLE98tyeu8r84ITHGE6iRv?= =?us-ascii?Q?RtWgvYx3rzfxe1SjuRrm01GjoqeGd58=3D?= Content-Type: multipart/alternative; boundary="_000_MAXPR01MB2878D9C1AA678996A79DFB3FE9D09MAXPR01MB2878INDP_" MIME-Version: 1.0 X-OriginatorOrg: iisc.ac.in X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM X-MS-Exchange-CrossTenant-Network-Message-Id: 2c2c804f-6039-4d85-2e5f-08da39a9c0ff X-MS-Exchange-CrossTenant-originalarrivaltime: 19 May 2022 15:10:47.6239 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 6f15cd97-f6a7-41e3-b2c5-ad4193976476 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: t218KNArt7sWI2yeYtYNfhSq+bYBkrmwnyRjYSs5sPhg76AG7w3LoX2A4P2mAaZncIg3DMieJ/9VFXNv5M/P1g== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MA0PR01MB7380 X-Seq: 50252 Archived-At: X-Loop: zsh-workers@zsh.org Errors-To: zsh-workers-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-workers-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: --_000_MAXPR01MB2878D9C1AA678996A79DFB3FE9D09MAXPR01MB2878INDP_ Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable I think that's a good idea to move with aim and plan. But could you clarify= few things. 1. What do you mean by rendering carefully formatted package documentation?= Is it similar to literate programming or something like doxygen? Or markdo= wn will be separate from source files. 2. I thought yodl was the tool currently being used to generate the documen= tation website. I'm not sure if it's also handling man page generation. Are= you considering a substitute for that approach? I do use markdown to write my static website and aware of a couple of good = frameworks which uses the markdown as a standard for content. But that can = only be a long-term strategy. I considered the markdown formatting and pruning of readme in this pr becau= se it could act as first step in making the documentation more accessible. = We could also extend it to all the remaining text files in the root of the = repo which do not affect the source or man page generation and bring a stru= cture to the documentation. Note: I'm assuming that these files do not affe= ct the source or man pages. Bevan Stanely bevs.xyz ________________________________ From: Peter Stephenson Sent: Thursday, May 19, 2022 2:25:18 PM To: Bevan Stanely ; zsh-workers@zsh.org Subject: Re: Proposal: Use Markdown syntax for README and other documentati= on External Email Markdown's fine for what it's does --- the only requirement I'd suggest bef= ore we start using it is that there is a firm plan to do something with it, e.g. integra= te it into a website. I've been a bit bemused before staring at carefully format= ted package documentation and wondering how I'm supposed to render it and havin= g done a bit of research tentatively concluded I'm probably not supposed to and th= en wondered what's the point and why I had to go through this exercise in the = first place... If there *is* a point, that's another matter. Pruning down README sounds sensible, too, though that probably needs a sepa= rate thread. pws --_000_MAXPR01MB2878D9C1AA678996A79DFB3FE9D09MAXPR01MB2878INDP_ Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable
I think that's a good idea to move with aim and plan. But= could you clarify few things.

1. What do you mean by rendering carefully formatted pack= age documentation? Is it similar to literate programming or something like = doxygen? Or markdown will be separate from source files.

2. I thought yodl was the tool currently being used to ge= nerate the documentation website. I'm not sure if it's also handling man pa= ge generation. Are you considering a substitute for that approach? 
I do use markdown to write my static website and aware of= a couple of good frameworks which uses the markdown as a standard for cont= ent. But that can only be a long-term strategy.

I considered the markdown formatting and pruning of readm= e in this pr because it could act as first step in making the documentation= more accessible. We could also extend it to all the remaining text files i= n the root of the repo which do not affect the source or man page generation and bring a structure to the docu= mentation. Note: I'm assuming that these files do not affect the source or = man pages.



Bevan Stanely
From: Peter Stephenson <= p.w.stephenson@ntlworld.com>
Sent: Thursday, May 19, 2022 2:25:18 PM
To: Bevan Stanely <bevanstanely@iisc.ac.in>; zsh-workers@zsh.o= rg <zsh-workers@zsh.org>
Subject: Re: Proposal: Use Markdown syntax for README and other docu= mentation
 
External Email


Markdown's fine for what it's does --- the only requirement I'd suggest bef= ore we start
using it is that there is a firm plan to do something with it, e.g. integra= te it
into a website.  I've been a bit bemused before staring at carefully f= ormatted
package documentation and wondering how I'm supposed to render it and havin= g done
a bit of research tentatively concluded I'm probably not supposed to and th= en
wondered what's the point and why I had to go through this exercise in the = first
place...  If there *is* a point, that's another matter.

Pruning down README sounds sensible, too, though that probably needs a sepa= rate
thread.

pws
--_000_MAXPR01MB2878D9C1AA678996A79DFB3FE9D09MAXPR01MB2878INDP_--