help / color / mirror / code / Atom feed
From: Bevan Stanely <bevanstanely@iisc.ac.in>
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
Date: Thu, 19 May 2022 15:10:47 +0000	[thread overview]
Message-ID: <MAXPR01MB2878D9C1AA678996A79DFB3FE9D09@MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM> (raw)
In-Reply-To: <1540829696.208973.1652950518801@mail2.virginmedia.com>

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


[-- Attachment #2: Type: text/html, Size: 3316 bytes --]

  reply	other threads:[~2022-05-19 15:11 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
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 [this message]
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=MAXPR01MB2878D9C1AA678996A79DFB3FE9D09@MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM \
    --to=bevanstanely@iisc.ac.in \
    --cc=p.w.stephenson@ntlworld.com \
    --cc=zsh-workers@zsh.org \
    --subject='Re: Proposal: Use Markdown syntax for README and other documentation' \


* 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:


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