zsh-workers
 help / color / mirror / code / Atom feed
* Proposal: Use Markdown syntax for README and other documentation
@ 2022-05-18 15:41 Bevan Stanely
  2022-05-19  1:10 ` Lawrence Velázquez
  0 siblings, 1 reply; 13+ messages in thread
From: Bevan Stanely @ 2022-05-18 15:41 UTC (permalink / raw)
  To: zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-18 15:41 Proposal: Use Markdown syntax for README and other documentation Bevan Stanely
@ 2022-05-19  1:10 ` Lawrence Velázquez
  2022-05-19  4:02   ` dana
  0 siblings, 1 reply; 13+ messages in thread
From: Lawrence Velázquez @ 2022-05-19  1:10 UTC (permalink / raw)
  To: Bevan Stanely; +Cc: zsh-workers

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  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  4:29     ` Bart Schaefer
  0 siblings, 2 replies; 13+ messages in thread
From: dana @ 2022-05-19  4:02 UTC (permalink / raw)
  To: Lawrence Velázquez; +Cc: Zsh hackers list, Bevan Stanely

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19  4:02   ` dana
@ 2022-05-19  4:26     ` Lawrence Velázquez
  2022-05-19  6:04       ` Bevan Stanely
  2022-05-19  4:29     ` Bart Schaefer
  1 sibling, 1 reply; 13+ messages in thread
From: Lawrence Velázquez @ 2022-05-19  4:26 UTC (permalink / raw)
  To: dana; +Cc: zsh-workers, Bevan Stanely

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19  4:02   ` dana
  2022-05-19  4:26     ` Lawrence Velázquez
@ 2022-05-19  4:29     ` Bart Schaefer
  1 sibling, 0 replies; 13+ messages in thread
From: Bart Schaefer @ 2022-05-19  4:29 UTC (permalink / raw)
  To: Zsh hackers list

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.


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19  4:26     ` Lawrence Velázquez
@ 2022-05-19  6:04       ` Bevan Stanely
  2022-05-19  8:55         ` Peter Stephenson
  0 siblings, 1 reply; 13+ messages in thread
From: Bevan Stanely @ 2022-05-19  6:04 UTC (permalink / raw)
  To: Lawrence Velázquez, dana; +Cc: zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19  6:04       ` Bevan Stanely
@ 2022-05-19  8:55         ` Peter Stephenson
  2022-05-19 15:10           ` Bevan Stanely
  0 siblings, 1 reply; 13+ messages in thread
From: Peter Stephenson @ 2022-05-19  8:55 UTC (permalink / raw)
  To: Bevan Stanely, zsh-workers

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19  8:55         ` Peter Stephenson
@ 2022-05-19 15:10           ` Bevan Stanely
  2022-05-19 15:16             ` Peter Stephenson
  0 siblings, 1 reply; 13+ messages in thread
From: Bevan Stanely @ 2022-05-19 15:10 UTC (permalink / raw)
  To: Peter Stephenson, zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19 15:10           ` Bevan Stanely
@ 2022-05-19 15:16             ` Peter Stephenson
  2022-05-19 15:22               ` Bevan Stanely
  0 siblings, 1 reply; 13+ messages in thread
From: Peter Stephenson @ 2022-05-19 15:16 UTC (permalink / raw)
  To: Bevan Stanely, zsh-workers

> 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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19 15:16             ` Peter Stephenson
@ 2022-05-19 15:22               ` Bevan Stanely
  2022-05-19 18:23                 ` Bevan Stanely
  0 siblings, 1 reply; 13+ messages in thread
From: Bevan Stanely @ 2022-05-19 15:22 UTC (permalink / raw)
  To: Peter Stephenson, zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19 15:22               ` Bevan Stanely
@ 2022-05-19 18:23                 ` Bevan Stanely
  2022-05-19 18:42                   ` Bart Schaefer
  0 siblings, 1 reply; 13+ messages in thread
From: Bevan Stanely @ 2022-05-19 18:23 UTC (permalink / raw)
  To: Peter Stephenson, zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19 18:23                 ` Bevan Stanely
@ 2022-05-19 18:42                   ` Bart Schaefer
  2022-05-20  5:43                     ` Bevan Stanely
  0 siblings, 1 reply; 13+ messages in thread
From: Bart Schaefer @ 2022-05-19 18:42 UTC (permalink / raw)
  To: Bevan Stanely; +Cc: Peter Stephenson, zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Proposal: Use Markdown syntax for README and other documentation
  2022-05-19 18:42                   ` Bart Schaefer
@ 2022-05-20  5:43                     ` Bevan Stanely
  0 siblings, 0 replies; 13+ messages in thread
From: Bevan Stanely @ 2022-05-20  5:43 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: zsh-workers

[-- 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 --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2022-05-20  5:44 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-05-18 15:41 Proposal: Use Markdown syntax for README and other documentation 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

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