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.3 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, 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 27431 invoked from network); 19 May 2022 04:29:38 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 19 May 2022 04:29:38 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1652934578; b=ZVsZ3hA+NwRaQK5j4Ei2w0+2Y7RvqVnXYzGFgFR3HPIapnzPgo0xCziPaRQyjNFb6PBYxhwtQE rs4Eid+uTAGHhQoc4lHeNMfWOXQeo8aryS9wBx3I8/lwubRclqZYmyFzKLTKb0/jaGSWQsGJX0 DWyPOKx59cU1mbeHL7PqujxUA/BVFPQBG+wmNY0wBSnks7EzPvGhgjEHjLK2pRHJO9ffydN3cW U9Q4h27Lq8dlzo2IPgewMYjWOfRC8UPxmBbOHSrL/cBlhHo9fgUsVcI/4cLxuWw6KfEeZarsi+ 5ZpWbKvxrccsJFU/GcNNbbzcP6iGvLYqp9pQXVoekX0x4w==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (mail-ej1-f42.google.com) smtp.remote-ip=209.85.218.42; dkim=pass header.d=brasslantern-com.20210112.gappssmtp.com header.s=20210112 header.a=rsa-sha256; dmarc=none header.from=brasslantern.com; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1652934578; bh=10YaqxV+kYuJibS/a3t1Cmxa+wCwNHEqkNfgNi3wt3M=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:Content-Type:To:Subject:Message-ID:Date:From:In-Reply-To: References:MIME-Version:DKIM-Signature:DKIM-Signature; b=dcjtYlQz9LjLZuIrmoba8JQotZR1u3LQvZ+Bpj/sijaHYlBr8YG10G5nJamy7UhobmZVZq+TVd TYfDCt5HevEzWnqJFGGrHDcw5Bn1iakgnpIzoFpvdUJTf1ggJogVKnqql9pzQVjP92CuT8HSw1 iNuKFpK5q6txzoHjuG3hL3/nhuAl70ItTmZeXy3SNKK2d8yNND6vgQMN9o3CBx1yVSROPMz8RH zNA4/0lZCW9OQH0R7RUVPJRYTgsSqvYHRGJMD9gzNPrmD8H0KqBizBjjf4kWac41B16uC50cEX nqACZyR0JDxwdvjj+BLqf0IAQ0AZNgBITO5szIO6XXivjQ==; 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-Type:To:Subject:Message-ID: Date:From:In-Reply-To:References:MIME-Version:Reply-To:Cc: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=xzAzXNtnsVP3OkA5jE9pZYUIJGqiOF+R7YPI/O1Iy1g=; b=TQSTbAg+r35fGmPmNIdwRap2Hh om4J3GioBA9fEd9sdj/69E5Nzcb7kvfNZg1hMuML3ScWdDJYfyL/ZTKl02kQHOofmGt8JQV2HSN3r 64hEFyQ0sJex37fgPnEjNQ47Nfop2/wGacVwlCaSB1fc2nEQxX+2IrmhNycQgp6JbYf0JUvHMBW06 M9xw/7tZdUsyjop3hcvucOXBERVfd+boFi8scuwebTxsIH8l7ouu2Wo+eWKuoCFv0M0P3mmruMYmy GKtcbeWI5f8uancOGNy80NEhPA3eCUoEmwpb8N2k3IraWHjGmib4VbEMlzQC0N07yAkgBZRMIptpK DV/KFOJQ==; Received: from authenticated user by zero.zsh.org with local id 1nrXn7-000F38-QA; Thu, 19 May 2022 04:29:37 +0000 Authentication-Results: zsh.org; iprev=pass (mail-ej1-f42.google.com) smtp.remote-ip=209.85.218.42; dkim=pass header.d=brasslantern-com.20210112.gappssmtp.com header.s=20210112 header.a=rsa-sha256; dmarc=none header.from=brasslantern.com; arc=none Received: from mail-ej1-f42.google.com ([209.85.218.42]:43730) by zero.zsh.org with esmtps (TLS1.3:TLS_AES_128_GCM_SHA256:128) id 1nrXms-000Eh7-7G; Thu, 19 May 2022 04:29:22 +0000 Received: by mail-ej1-f42.google.com with SMTP id m20so7522594ejj.10 for ; Wed, 18 May 2022 21:29:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=brasslantern-com.20210112.gappssmtp.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=xzAzXNtnsVP3OkA5jE9pZYUIJGqiOF+R7YPI/O1Iy1g=; b=i94rkv4Jo0n7SBrrBCxK/gZSfayaDMSxo7xmuIG5nl5/FQaGlIcPhacU/0QRigg8+I 7VW9tgDTkkGLV6l8pec2eQpsq949bBIzj2wj5PZOAQPOXYcpi1bKZmDSJnTUu7UKjaZX NG42dRrf2Pu254R79NAjYm5wQbeXIs26ywrOCgUKYkTYH8YUC1TpjNYpjOyUbF8veSGn 9vh525XpYj7ofXdlQPCuSABriXnQkb6+7xHSLQhSRtqwvGKWR2gChXJN1yaz56j3izrj UopJCT5d/Vmzs+JzyimY0S5GRBtLezRU2ceWJtsxvkFmiGY32tlqfCtBkZT8u65y3lFj 5/Gw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=xzAzXNtnsVP3OkA5jE9pZYUIJGqiOF+R7YPI/O1Iy1g=; b=muhdsFYEUVHpuv61i14d+TycXDps44yPzaD4qk2dya3lsVgbX6Rf75zIvyrtIER7jn 3kN7HWBQl8KbDCq60u7b83FXHcaCgPbaL5DiYi6/KWD49qXlXsstONVkkWFFJgBgbOm7 EiV+yKSx1qhewmqfbEziVsD/A1Muzy3sMsWafrMDjUFSZAjtyqJ/3Ew1J7QIlmS9fH3L du56o5vUlpoMMnVGbYY5+xKuH87KPu0QJ5XdvrFyKVQtpitNFEbDELk2NZBPlDvD58bF jbdg0avIMX+0QpRJrt0gZ0+8F1G217hzj/Yo91BRPfwAHkPe3xOIbqEz0FfGHWAQ5ma/ 19CA== X-Gm-Message-State: AOAM531wgEB0KOfndHbPAqAjO03hCSPqlSI/joDeEljbqDzpaYiuj5OJ kU4qLfoHby5xH5iEr9Z1hrYu57GBHbvpcmra1T+uzxkLVHM= X-Google-Smtp-Source: ABdhPJwizn2TL/a68QKsGhd6uZr1MxffmQwwPS2uvEb6CNaNm0Q09/Pj5O2dMS14ICM6kojASNwAC5o3hdq0gGJWJgs= X-Received: by 2002:a17:907:62a0:b0:6fe:69f3:88de with SMTP id nd32-20020a17090762a000b006fe69f388demr2475619ejc.214.1652934561956; Wed, 18 May 2022 21:29:21 -0700 (PDT) MIME-Version: 1.0 References: <33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com> In-Reply-To: From: Bart Schaefer Date: Wed, 18 May 2022 21:29:10 -0700 Message-ID: Subject: Re: Proposal: Use Markdown syntax for README and other documentation To: Zsh hackers list Content-Type: text/plain; charset="UTF-8" X-Seq: 50249 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 9:03 PM dana wrote: > > I don't feel *super* strongly about this, but i have thought before that > the README/NEWS dichotomy was slightly confusing Yeah, I don't recall how we got into the habit of putting an increasingly large "incompatibilities" section into README. It made some sense for 4.2 to 5.0 and even from 5.0 to 5.3, but at this point some of the prose in the older parts of that is more confusing than helpful. The NEWS file on the other hand is sort of a Cliffs Notes version of the ChangeLog -- condensed but with discussion of the high points. > and that maybe the > average person would prefer it if the README just had a shorter overview I certainly wouldn't object to moving the older (in)compatibility discussions somewhere else. How many people are likely to be upgrading all the way from 4.2 at this point? > I don't think it'd be a big change to have the README standardise on some > sub-set of Markdown to make it look a little nicer on code-hosting sites, > as long as we continued to avoid the more advanced/noisy features like > images and hyper-links I find myself unable to muster enthusiasm on either side. My personal feeling is that markdown is just annoying, then I also find GUI repo tools annoying.