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

[John MacFarlane]

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