Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

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

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
From: Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>
Sent: Thursday, May 19, 2022 2:25:18 PM
To: Bevan Stanely <bevanstanely@xxxxxxxxxx>; zsh-workers@xxxxxxx <zsh-workers@xxxxxxx>
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
Messages sorted by: Reverse Date, Date, Thread, Author