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

[Roman Cheplyaka]

* Ivan Lazar Miljenovic <ivan.miljenovic at gmail.com> [2013-04-08 10:18:32+1000]
> 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

This seems to be a different issue — about unlit, not cpp.

> > * 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