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

[Roman Cheplyaka]

Looks like a bug in cpphs to me (CC'ing Malcolm). It should respect
comments. E.g. GNU cpp strips C comments.

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