help / color / mirror / code / Atom feed
From: "Lawrence Velázquez" <larryv@zsh.org>
To: "Bevan Stanely" <bevanstanely@iisc.ac.in>
Cc: zsh-workers@zsh.org
Subject: Re: Proposal: Use Markdown syntax for README and other documentation
Date: Wed, 18 May 2022 21:10:00 -0400	[thread overview]
Message-ID: <33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com> (raw)
In-Reply-To: <MA1PR01MB28762D3415101EC7AC989DBEE9D19@MA1PR01MB2876.INDPRD01.PROD.OUTLOOK.COM>

On Wed, May 18, 2022, at 11:41 AM, Bevan Stanely wrote:
> `I have proposal to use markdown syntax for the README and other 
> documentation in the project repo. Presently the files adhere to the 
> minimal styling from alternate syntax 
> <https://www.markdownguide.org/basic-syntax/#alternate-syntax> which 
> mainly comprises of two levels of headings. Also there is no `.md`​ 
> file extensions, which prevents markdown recognition by offline editors 
> and Github.`

There are no file extensions because these files are not Markdown

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 
> incompatibilities to the file COMPATIBILITY

I don't really have an opinion on this part.

> and formatted the shorter 
> README with markdown in this PR 
> <https://github.com/zsh-users/zsh/pull/92>. You may have a look at the 
> file, as rendered by Github here 
> <https://github.com/bevsxyz/zsh#readme>. I think the efforts will 
> 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.


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.


  reply	other threads:[~2022-05-19  1:10 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 [this message]
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

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=33e425a1-36a6-4fa6-8a59-a892a7861d93@www.fastmail.com \
    --to=larryv@zsh.org \
    --cc=bevanstanely@iisc.ac.in \
    --cc=zsh-workers@zsh.org \


* 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


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).