Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
On Thu, Apr 4, 2013 at 11:22 PM, Kim-Ee Yeoh k...@atamo.com wrote: Could you say something about /why/ you make the suggestion? I, for one, would be happy to google and read links, but what's missing from that experience would be input from a fellow haskeller. In context. In real-time. On topic. Pretty much the same reasons Richard O'Keefe has already said more vigorously: Markdown is ambiguous, and thus difficult to write good parsers for, and that makes it hard to write good text that does exactly what you want without struggling and clawing at it and eventually just using some dirty hack workaround you found on Google. Or changing your document's contents to handle a formatting bug/misdesign. People may say well Markdown has won, in which case Markdown _has_ won. But there are still plenty of good alternatives out there that are widely used (RST is just my personal favorite). And there since there are good alternatives out there which don't have these problems, why not use them instead? I didn't really want to start a markup-language-flame-war... except that I'm glad that people are discussing it and thinking about these issues... So maybe I did. :-( Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
I humbly suggest reStructuredText rather than Markdown, which is what
is used by the Python community for documentation. Since it's specifically
made for documentation it may be nicer. But, I don't want to spark
a format argument.
There is also the Pandoc program, which is a universal-ish markup-
language-converter, conveniently written in Haskell. Might be a place
to start for this, regardless of the language chosen:
http://www.johnmacfarlane.net/pandoc/
Simon
Excerpts from Johan Tibell's message of 2013-04-04 09:49:04 -0700:
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: http://trac.haskell.org/haddock/ticket/244
-- Johan
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] IPv6 issues for (code|community).haskell.org?
Confirmed for me on IPv6 as well. -- Simon Heath http://alopex.li/ Science, games, computers, life. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haskell IDE
Emacs. haskell-mode is also rather slicker than most emacs major modes I've seen; it recognizes syntax as you type, does the right thing with indentation levels, and so on. -- Simon Heath icefo...@gmail.com Follow your heart, and keep on rocking. http://alopex.li/ ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
