From: "Lawrence Velázquez" <firstname.lastname@example.org> To: "Bevan Stanely" <email@example.com> Cc: firstname.lastname@example.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: <email@example.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 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
next prev parent 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: 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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: Proposal: Use Markdown syntax for README and other documentation' \ /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
Code repositories for project(s) associated with this 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).