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

[Ivan Lazar Miljenovic]

On 8 April 2013 07:12, Roman Cheplyaka <roma at ro-che.info> wrote:
> Looks like a bug in cpphs to me (CC'ing Malcolm). It should respect
> comments. E.g. GNU cpp strips C comments.

Not quite: http://hackage.haskell.org/trac/ghc/ticket/4836

>
> Roman
>
> * John MacFarlane <jgm at berkeley.edu> [2013-04-05 16:04:32-0700]
>> I like markdown and use it all the time.  While I acknowledge the
>> problems that have been pointed out, markdown has the advantage of being
>> easily readable "as it is" in the source document, and not looking like
>> markup.
>>
>> But I do want to point out one problem with markdown as a format for
>> documentation in Haskell files.  Consider:
>>
>> ----------------------------------------------------
>> module MyModule
>> {-
>> # Introduction
>>
>> This is my module
>> -}
>> where
>> import System.Environment
>>
>> main = getArgs >>= print
>> ----------------------------------------------------
>>
>> Now try to compile with -cpp, and you'll get an error because of the '#'
>> in column 1.  '#' in column 1 is common in markdown (and even
>> indispensible for level 3+ headers).
>>
>> One could work around this by disallowing level 3+ headers, by allowing
>> the headers to be indented, or by introducing new setext-like syntax for
>> level 3+ headers, but it is a problem for the idea of using a markdown
>> SUPERset.
>>
>> John
>>
>> +++ dag.odenhall at gmail.com [Apr 05 13 21:59 ]:
>> >    I forgot the mention the craziness with the *significant trailing
>> >    whitespace*.
>> >
>> >    On Fri, Apr 5, 2013 at 9:49 PM, [1]dag.odenhall at gmail.com
>> >    <[2]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
>> >    <[3]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: [4]http://trac.haskell.org/haddock/ticket/244
>> >      -- Johan
>> >      _______________________________________________
>> >      Haskell-Cafe mailing list
>> >      [5]Haskell-Cafe at haskell.org
>> >      [6]http://www.haskell.org/mailman/listinfo/haskell-cafe
>> >
>> > References
>> >
>> >    1. mailto:dag.odenhall at gmail.com
>> >    2. mailto:dag.odenhall at gmail.com
>> >    3. mailto:johan.tibell at gmail.com
>> >    4. http://trac.haskell.org/haddock/ticket/244
>> >    5. mailto:Haskell-Cafe at haskell.org
>> >    6. 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
>>
>>
>> _______________________________________________
>> 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