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

[Ivan Lazar Miljenovic]

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
> 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 <ok at cs.otago.ac.nz>
> 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 at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>



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