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.odenh...@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.odenh...@gmail.com
> <[2]dag.odenh...@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.tib...@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@haskell.org
> [6]http://www.haskell.org/mailman/listinfo/haskell-cafe
>
> References
>
> 1. mailto:dag.odenh...@gmail.com
> 2. mailto:dag.odenh...@gmail.com
> 3. mailto:johan.tib...@gmail.com
> 4. http://trac.haskell.org/haddock/ticket/244
> 5. mailto:Haskell-Cafe@haskell.org
> 6. http://www.haskell.org/mailman/listinfo/haskell-cafe
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe@haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
