help / color / mirror / code / Atom feed
From: dana <dana@dana.is>
To: "Lawrence Velázquez" <larryv@zsh.org>
Cc: "Zsh hackers list" <zsh-workers@zsh.org>,
	"Bevan Stanely" <bevanstanely@iisc.ac.in>
Subject: Re: Proposal: Use Markdown syntax for README and other documentation
Date: Wed, 18 May 2022 23:02:29 -0500	[thread overview]
Message-ID: <eb6c47d6-d40e-4436-a02d-4f56df06282f@www.fastmail.com> (raw)
In-Reply-To: <33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com>

On Wed 18 May 2022, at 10:41, Bevan Stanely wrote:
> As an initial step, I have separated out the list of backward
> incompatibilities to the file COMPATIBILITY and formatted the shorter

I don't feel *super* strongly about this, but i have thought before that
the README/NEWS dichotomy was slightly confusing, and that maybe the
average person would prefer it if the README just had a shorter overview
of the most important information. Not sure about the naming convention
but i would personally be OK with breaking the changes out into another
file, or combining it with NEWS, and improving the formatting and
structure of the rest of the README

On Wed 18 May 2022, at 20:10, Lawrence Velázquez wrote:
> While nice for editing, raw markup (even Markdown) makes for a poor
> reading experience.

I don't think that's necessarily the case, as demonstrated by the fact
that Bevan thought we were already using Markdown lol. And we very nearly

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

But i feel even less strongly about that than the other thing


  reply	other threads:[~2022-05-19  4:03 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-05-18 15:41 Bevan Stanely
2022-05-19  1:10 ` Lawrence Velázquez
2022-05-19  4:02   ` dana [this message]
2022-05-19  4:26     ` Lawrence Velázquez
2022-05-19  6:04       ` Bevan Stanely
2022-05-19  8:55         ` Peter Stephenson
2022-05-19 15:10           ` Bevan Stanely
2022-05-19 15:16             ` Peter Stephenson
2022-05-19 15:22               ` Bevan Stanely
2022-05-19 18:23                 ` Bevan Stanely
2022-05-19 18:42                   ` Bart Schaefer
2022-05-20  5:43                     ` Bevan Stanely
2022-05-19  4:29     ` Bart Schaefer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=eb6c47d6-d40e-4436-a02d-4f56df06282f@www.fastmail.com \
    --to=dana@dana.is \
    --cc=bevanstanely@iisc.ac.in \
    --cc=larryv@zsh.org \
    --cc=zsh-workers@zsh.org \
    --subject='Re: Proposal: Use Markdown syntax for README and other documentation' \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).