[Haskell-cafe] Markdown extension for Haddock as a GSoC project
Ivan Lazar Miljenovic
ivan.miljenovic at gmail.com
Mon Apr 29 10:47:58 CEST 2013
On 29 April 2013 18:16, Alexander Kjeldaas <alexander.kjeldaas at gmail.com> 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
> 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
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
> On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe <ok at cs.otago.ac.nz>
>> 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
>> 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 at haskell.org
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
More information about the Haskell-Cafe