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=-3.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, T_SCC_BODY_TEXT_LINE,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 2181 invoked from network); 19 May 2022 01:10:45 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 19 May 2022 01:10:45 -0000 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:Content-Transfer-Encoding: Content-Type:Subject:Cc:To:From:Date:References:In-Reply-To:Message-Id: Mime-Version:Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=ROjTpKYNcw0VrGs/SeYCUV+xMamUFARisT5xx6aUb+E=; b=XVZUvwfklcLZHUX6xCkPaogZwy KfiaYSDbsDDm8fb93aREhrJR6SNF4IZUrxPLJfJM56E7rGl1f6H23q4d61U8DQkrzltZcRxosLi9p 0bz4gBevMfACk45QAbGkAcEA0G5MacbGkKC5Xf6nh3WMnuxDuYXeq2eJNJYxaFffNnyg6Ulxvv9MR ufhJ0S4ItNsSXLoeuNGNfDY+PaxC5cAvCDsg0MQ6YhvPDOWwupZG5eX6NY4TEWkCK+yqGcJ2xf38x Bwr8kTN1vn0UqnYAvoHP3SlTeHdLGshsZWdCpueWb9wIiLCeGZcjDI5+Q2BZDywzPVSWFb8p5Y/sF TKszdA/A==; Received: from authenticated user by zero.zsh.org with local id 1nrUge-0006R4-Jr; Thu, 19 May 2022 01:10:44 +0000 Received: from authenticated user by zero.zsh.org with esmtpsa (TLS1.3:TLS_AES_256_GCM_SHA384:256) id 1nrUgM-00067k-H4; Thu, 19 May 2022 01:10:26 +0000 Received: from compute2.internal (compute2.nyi.internal [10.202.2.46]) by mailauth.nyi.internal (Postfix) with ESMTP id 9CD4727C0054; Wed, 18 May 2022 21:10:24 -0400 (EDT) Received: from imap48 ([10.202.2.98]) by compute2.internal (MEProxy); Wed, 18 May 2022 21:10:24 -0400 X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvfedriedtgdeggecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenog fuuhhsphgvtghtffhomhgrihhnucdlgeelmdenucfjughrpefofgggkfgjfhffhffvvefu tgfgsehtqhertderreejnecuhfhrohhmpefnrgifrhgvnhgtvggpgggvlhojiihquhgvii cuoehlrghrrhihvhesiihshhdrohhrgheqnecuggftrfgrthhtvghrnhepieegteehueej keejveelledtvdffkeetjeeiveevtdehteelgeevkeeijefhleejnecuffhomhgrihhnpe hmrghrkhguohifnhhguhhiuggvrdhorhhgpdhgihhthhhusgdrtghomhdpshhouhhrtggv fhhorhhgvgdrnhgvthenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrih hlfhhrohhmpehlrghrrhihvhdomhgvshhmthhprghuthhhphgvrhhsohhnrghlihhthidq udduhedukeejjedtgedqudduledvjeefkeehqdhlrghrrhihvheppeiishhhrdhorhhgse hfrghsthhmrghilhdrtghomh X-ME-Proxy: Feedback-ID: iaa214773:Fastmail Received: by mailuser.nyi.internal (Postfix, from userid 501) id EEDAA31A0061; Wed, 18 May 2022 21:10:23 -0400 (EDT) X-Mailer: MessagingEngine.com Webmail Interface User-Agent: Cyrus-JMAP/3.7.0-alpha0-591-gfe6c3a2700-fm-20220427.001-gfe6c3a27 Mime-Version: 1.0 Message-Id: <33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com> In-Reply-To: References: Date: Wed, 18 May 2022 21:10:00 -0400 From: =?UTF-8?Q?Lawrence_Vel=C3=A1zquez?= To: "Bevan Stanely" Cc: zsh-workers@zsh.org Subject: Re: Proposal: Use Markdown syntax for README and other documentation Content-Type: text/plain;charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Seq: 50245 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: On Wed, May 18, 2022, at 11:41 AM, Bevan Stanely wrote: > `I have proposal to use markdown syntax for the README and other=20 > documentation in the project repo. Presently the files adhere to the=20 > minimal styling from alternate syntax=20 > which=20 > mainly comprises of two levels of headings. Also there is no `.md`=E2=80= =8B=20 > file extensions, which prevents markdown recognition by offline editor= s=20 > and Github.` There are no file extensions because these files are not Markdown files. I do not think we should embellish the plain text documentation with *any* markup language, unless we decide that we no longer care about accommodating users who wish to read the plain text files. While nice for editing, raw markup (even Markdown) makes for a poor reading experience. (I can't in good conscience recommend this approach, but in my personal repositories I often end up maintaining two parallel README documents -- one in a markup language and one in un-marked-up plain text -- because all but the most bare-bones markup rapidly becomes unusable for reading directly.) > As an initial step, I have separated out the list of backward=20 > incompatibilities to the file COMPATIBILITY I don't really have an opinion on this part. > and formatted the shorter=20 > README with markdown in this PR=20 > . You may have a look at the=20 > file, as rendered by Github here=20 > . I think the efforts will=20 > enable the documentation to be more accessible and easy to navigate. This project is hosted on SourceForge, not GitHub. It seems that SF will render Markdown, but I don't know what software they use to do so, nor which flavors they support. https://sourceforge.net/p/forge/documentation/Files-Readme/ So not only would converting these documents to Markdown mean that everyone who edits them would have to worry about writing valid Markdown, they'd have to worry about whether their changes will work with (possibly) multiple Markdown implementations. --=20 vq