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@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@gmail.com <[2]dag.odenhall@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@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.odenhall@gmail.com 2. mailto:dag.odenhall@gmail.com 3. mailto:johan.tibell@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