Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project

On 29 April 2013 18:16, Alexander Kjeldaas wrote:

I see the pluggable markup being pushed in this thread again.

I just want to remind everybody that we currently have a flavor of a markup issue on github.

The ghc source code uses literal haskell, and it does not work well on github.

http://www.haskell.org/pipermail/ghc-devs/2013-April/001099.html

Any markup that is not widely supported makes it harder for third parties to support and parse.

The solution is *not* to reimplement github in haskell, but to standardize markup as much as possible.

Pluggable markup makes the probability that a github-like service, IDEs and similar can make use of the documentation arbitrarily close to zero.

If it's pluggable, doesn't it make the situation _worse_, as you choose a plug-in that works with one service but then fails for all the others? I think this is a bit of a non-issue: services like github should _not_ mark-up documentation (as you're going to have some kind of issue where it's rendered when you didn't expect it or vice-versa, thus making it different to read the actual code). I tend to agree with Richard, etc.: I'd rather either extend the existing Haddock mark-up or choose a sane markup language if we wish to replace/augment it (I use markup, but find a lot of its conventions appalling).

Alexander

On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe wrote:

...

I should add that as a consumer of Haddock documentation I can testify that fancier styling (in whatever format) would be of little benefit to _me_. What I need is more plain text and more examples.

To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation.

So I do agree that markup that doesn't get in the way of a _reader_ who is looking at the source code is an excellent thing.

I say this as someone who had to read some Java today and ended up stuffing it through a comment stripper so that I could easily find what I needed to find.

This thread is not about the "visually lightweight" aspect of Markdown. That's a good thing. No argument there.

The thread is about how well documented the notation should be.

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

-- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com http://IvanMiljenovic.wordpress.com