[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock

[dag.odenhall at gmail.com]

I forgot the mention the craziness with the *significant trailing
whitespace*.


On Fri, Apr 5, 2013 at 9:49 PM, dag.odenhall at gmail.com <
dag.odenhall at gmail.com> wrote:

> Personally I think Markdown sucks, although perhaps less than Haddock
> markup.
>
> Still:
>
> * No document meta data
> * No code block meta data like language for syntax highlighting
> * No tables
> * No footnotes
> * HTML fallback is insecure
> * Confusing syntax (is it []() or ()[] for links?)
> * Syntax that gets in the way (maybe I don't want *stars* emphasized)
> * Above point leads to non-standard dialects like "GitHub Markdown" (no,
> GitHub doesn't use markdown)
> * Not extensible, leading to even more non-standard hacks and work-arounds
> (GitHub Markdown, Pandoc Markdown, other Markdown libraries have their own
> incompatible extensions)
> * Not well suited for web input (e.g. four-space indentation for code
> blocks), although not that important for Haddock
>
> An important thing to note here is that no, Markdown has *not* won because
> no one is actually using *Markdown*.  They're using their own, custom and
> incompatible dialects.
>
> Only two of the above points apply to reStructuredText (web input and
> syntax getting in the way), and those particular points don't apply to
> Creole.  Therefore I tend to advocate Creole for web applications and
> reStructuredText for documents.
>
> On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell <johan.tibell at gmail.com>wrote:
>
>> Hi all,
>>
>> Haddock's current markup language leaves something to be desired once
>> you want to write more serious documentation (e.g. several paragraphs
>> of introductory text at the top of the module doc). Several features
>> are lacking (bold text, links that render as text instead of URLs,
>> inline HTML).
>>
>> I suggest that we implement an alternative haddock syntax that's a
>> superset of Markdown. It's a superset in the sense that we still want
>> to support linkifying Haskell identifiers, etc. Modules that want to
>> use the new syntax (which will probably be incompatible with the
>> current syntax) can set:
>>
>> {-# HADDOCK Markdown #-}
>>
>> on top of the source file.
>>
>> Ticket: http://trac.haskell.org/haddock/ticket/244
>>
>> -- Johan
>>
>> _______________________________________________
>> Haskell-Cafe mailing list
>> Haskell-Cafe at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130405/1e7bc1b4/attachment.htm>