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

[Evan Laforge]

Can't we just add some features to haddock?  There are a lot of ways
to improve haddock a lot, and no one is doing them, so my impression
is that haddock doesn't really have active maintainers.  Adding a
whole new backend seems risky, unless it results in new maintainers
joining.

For my personal bikeshed contribution, I would like to see haddock
move in the way of fewer markup characters and rules, not more.  Since
haddock is not "statically checked", the only way to find out if I put
in an error is to run haddock and then visually inspect the output,
unless of course it was a syntax error, in which case the error
message is often not very good.  I can easily haddock individual files
since I have a custom build system, but I imagine cabal users would
have to haddock the entire project every time.  I regularly see
haddock errors in released packages so I'm not the only one.

There are lots of ways to improve haddock a lot.  For example, better
parse error messages.  Make ""s smarter so they don't try to link
things that are obviously not modules.  Or complain if it's not a
module.  Or better, get rid of them entirely and use single quotes for
that.  And make single quotes work for non-imported symbols.
Incremental support for cabal.  Perhaps even deprecate @ and use ' for
that too.

One thing I think HTML got right is that there are only two characters
that need to be quoted.  Of course that's at the cost of all the
markup being wordy, but the more you move in the markup-style DWIM the
more little rules you have to remember.


On Thu, Apr 4, 2013 at 6:00 PM, Johan Tibell <johan.tibell at gmail.com> wrote:
>> Would it be too much to ask that a notation be used which has
>> a formal syntax and a formal semantics?
>
> We will document our superset, sure. That's what others did as well.
> The point is using Markdown as the shared base.
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe