[-- Attachment #1: Type: text/plain, Size: 895 bytes --] Hello, 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. As an initial step, I have separated out the list of backward incompatibilities to the file COMPATIBILITY 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. Let me know your thoughts on the matter! Bevan Stanely bevs.xyz<https://bevs.xyz> [-- Attachment #2: Type: text/html, Size: 3284 bytes --]
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
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 > README 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 are 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 dana
On Thu, May 19, 2022, at 12:02 AM, dana wrote: > 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 > are I agree that Markdown is not bad if limited to the quieter markup (e.g., headings, strong, emphasis, lists, blockquotes, etc.). Those also tend to be decently portable between implementations. The problem is that it's always tempting to move on to the less-quiet markup :-/ > 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 The PR in question introduces both of those things, as well as raw HTML (which SourceForge would sanitize away) and backslash escaping. -- vq
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.
[-- Attachment #1: Type: text/plain, Size: 1761 bytes --] This is the git tree of my commit in Sourceforge before I removed the raw HTML according to vq's opinion. It renders it fine. The only issue was the file extension. I understand the reasons for dreading any markup, it's just a proposal anyway if it's too inconvenient we can always drop the idea. https://sourceforge.net/p/zsh-fork/code/ci/a205af4809fbe2335438e6b83c1b55bdabba5504/tree/ ________________________________ From: Lawrence Velázquez <larryv@zsh.org> Sent: 19 May 2022 09:56 To: dana <dana@dana.is> Cc: zsh-workers@zsh.org <zsh-workers@zsh.org>; Bevan Stanely <bevanstanely@iisc.ac.in> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email On Thu, May 19, 2022, at 12:02 AM, dana wrote: > 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 > are I agree that Markdown is not bad if limited to the quieter markup (e.g., headings, strong, emphasis, lists, blockquotes, etc.). Those also tend to be decently portable between implementations. The problem is that it's always tempting to move on to the less-quiet markup :-/ > 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 The PR in question introduces both of those things, as well as raw HTML (which SourceForge would sanitize away) and backslash escaping. -- vq [-- Attachment #2: Type: text/html, Size: 3102 bytes --]
Markdown's fine for what it's does --- the only requirement I'd suggest before we start using it is that there is a firm plan to do something with it, e.g. integrate it into a website. I've been a bit bemused before staring at carefully formatted package documentation and wondering how I'm supposed to render it and having done a bit of research tentatively concluded I'm probably not supposed to and then wondered what's the point and why I had to go through this exercise in the first place... If there *is* a point, that's another matter. Pruning down README sounds sensible, too, though that probably needs a separate thread. pws
[-- Attachment #1: Type: text/plain, Size: 2089 bytes --] I think that's a good idea to move with aim and plan. But could you clarify few things. 1. What do you mean by rendering carefully formatted package documentation? Is it similar to literate programming or something like doxygen? Or markdown will be separate from source files. 2. I thought yodl was the tool currently being used to generate the documentation website. I'm not sure if it's also handling man page generation. Are you considering a substitute for that approach? I do use markdown to write my static website and aware of a couple of good frameworks which uses the markdown as a standard for content. But that can only be a long-term strategy. I considered the markdown formatting and pruning of readme in this pr because it could act as first step in making the documentation more accessible. We could also extend it to all the remaining text files in the root of the repo which do not affect the source or man page generation and bring a structure to the documentation. Note: I'm assuming that these files do not affect the source or man pages. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Peter Stephenson <p.w.stephenson@ntlworld.com> Sent: Thursday, May 19, 2022 2:25:18 PM To: Bevan Stanely <bevanstanely@iisc.ac.in>; zsh-workers@zsh.org <zsh-workers@zsh.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email Markdown's fine for what it's does --- the only requirement I'd suggest before we start using it is that there is a firm plan to do something with it, e.g. integrate it into a website. I've been a bit bemused before staring at carefully formatted package documentation and wondering how I'm supposed to render it and having done a bit of research tentatively concluded I'm probably not supposed to and then wondered what's the point and why I had to go through this exercise in the first place... If there *is* a point, that's another matter. Pruning down README sounds sensible, too, though that probably needs a separate thread. pws [-- Attachment #2: Type: text/html, Size: 3316 bytes --]
> On 19 May 2022 at 16:10 Bevan Stanely <bevanstanely@iisc.ac.in> wrote: > 1. What do you mean by rendering carefully formatted package documentation? > Is it similar to literate programming or something like doxygen? Or > markdown will be separate from source files. That was simply a slightly cryptic reference to use of markdown I've seen in other settings. > 2. I thought yodl was the tool currently being used to generate the > documentation website. I'm not sure if it's also handling man page > generation. Are you considering a substitute for that approach? Yodl is used for all internal documentation, including manual pages; as it's working OK I don't think discussions to change that have ever got very far --- it's easy to plan for, massively harder to do. I would imagine markdown, if used at all, would be restricted to a few package files that are currently plain text. pws
[-- Attachment #1: Type: text/plain, Size: 1448 bytes --] Thanks for the clarification. > I would imagine markdown, if used at all, would be restricted to a few package files that are currently plain text. I agree. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Peter Stephenson <p.w.stephenson@ntlworld.com> Sent: Thursday, May 19, 2022 8:46:18 PM To: Bevan Stanely <bevanstanely@iisc.ac.in>; zsh-workers@zsh.org <zsh-workers@zsh.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email > On 19 May 2022 at 16:10 Bevan Stanely <bevanstanely@iisc.ac.in> wrote: > 1. What do you mean by rendering carefully formatted package documentation? > Is it similar to literate programming or something like doxygen? Or > markdown will be separate from source files. That was simply a slightly cryptic reference to use of markdown I've seen in other settings. > 2. I thought yodl was the tool currently being used to generate the > documentation website. I'm not sure if it's also handling man page > generation. Are you considering a substitute for that approach? Yodl is used for all internal documentation, including manual pages; as it's working OK I don't think discussions to change that have ever got very far --- it's easy to plan for, massively harder to do. I would imagine markdown, if used at all, would be restricted to a few package files that are currently plain text. pws [-- Attachment #2: Type: text/html, Size: 3589 bytes --]
[-- Attachment #1: Type: text/plain, Size: 1906 bytes --] Also one followup question, is yodl generating the documentation website as well? The .org and sourceforge ones. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Bevan Stanely <bevanstanely@iisc.ac.in> Sent: Thursday, May 19, 2022 8:52:41 PM To: Peter Stephenson <p.w.stephenson@ntlworld.com>; zsh-workers@zsh.org <zsh-workers@zsh.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation Thanks for the clarification. > I would imagine markdown, if used at all, would be restricted to a few package files that are currently plain text. I agree. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Peter Stephenson <p.w.stephenson@ntlworld.com> Sent: Thursday, May 19, 2022 8:46:18 PM To: Bevan Stanely <bevanstanely@iisc.ac.in>; zsh-workers@zsh.org <zsh-workers@zsh.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email > On 19 May 2022 at 16:10 Bevan Stanely <bevanstanely@iisc.ac.in> wrote: > 1. What do you mean by rendering carefully formatted package documentation? > Is it similar to literate programming or something like doxygen? Or > markdown will be separate from source files. That was simply a slightly cryptic reference to use of markdown I've seen in other settings. > 2. I thought yodl was the tool currently being used to generate the > documentation website. I'm not sure if it's also handling man page > generation. Are you considering a substitute for that approach? Yodl is used for all internal documentation, including manual pages; as it's working OK I don't think discussions to change that have ever got very far --- it's easy to plan for, massively harder to do. I would imagine markdown, if used at all, would be restricted to a few package files that are currently plain text. pws [-- Attachment #2: Type: text/html, Size: 4469 bytes --]
[-- Attachment #1: Type: text/plain, Size: 298 bytes --] On Thu, May 19, 2022 at 11:24 AM Bevan Stanely <bevanstanely@iisc.ac.in> wrote: > Also one followup question, is yodl generating the documentation website > as well? The .org and sourceforge ones. > Yodl generates the manual page HTML and the FAQ but the "front page" of each site is hand-coded. [-- Attachment #2: Type: text/html, Size: 612 bytes --]
[-- Attachment #1: Type: text/plain, Size: 764 bytes --] That's interesting. Thanks. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Bart Schaefer <schaefer@brasslantern.com> Sent: Friday, May 20, 2022 12:12:01 AM To: Bevan Stanely <bevanstanely@iisc.ac.in> Cc: Peter Stephenson <p.w.stephenson@ntlworld.com>; zsh-workers@zsh.org <zsh-workers@zsh.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email On Thu, May 19, 2022 at 11:24 AM Bevan Stanely <bevanstanely@iisc.ac.in<mailto:bevanstanely@iisc.ac.in>> wrote: Also one followup question, is yodl generating the documentation website as well? The .org and sourceforge ones. Yodl generates the manual page HTML and the FAQ but the "front page" of each site is hand-coded. [-- Attachment #2: Type: text/html, Size: 2068 bytes --]