From: Bart Schaefer <schaefer@brasslantern.com>
To: Zsh hackers list <zsh-workers@zsh.org>
Subject: Re: Proposal: Use Markdown syntax for README and other documentation
Date: Wed, 18 May 2022 21:29:10 -0700 [thread overview]
Message-ID: <CAH+w=7ahVEfvDdvjR9=f=Y55D5zdHKGDifr17R0yuW2uikshug@mail.gmail.com> (raw)
In-Reply-To: <eb6c47d6-d40e-4436-a02d-4f56df06282f@www.fastmail.com>
On Wed, May 18, 2022 at 9:03 PM dana <dana@dana.is> 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.
prev parent reply other threads:[~2022-05-19 4:29 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
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 [this message]
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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAH+w=7ahVEfvDdvjR9=f=Y55D5zdHKGDifr17R0yuW2uikshug@mail.gmail.com' \
--to=schaefer@brasslantern.com \
--cc=zsh-workers@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
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).