Re: Proposal: Use Markdown syntax for README and other documentation

[Lawrence Velázquez <larryv@xxxxxxx>]

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

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.

-- 
vq