[Haskell-cafe] Markdown extension for Haddock as a GSoC project

Sat Apr 27 11:23:44 CEST 2013

How's about Creole?
http://wikicreole.org/

Found it via this:
http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/

If you go with Markdown, I vote for one of the Pandoc implementations,
probably Pandoc (strict):
http://johnmacfarlane.net/babelmark2/

(at least then we're not creating yet another standard...)

Alistair

On 24 April 2013 07:23, Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk> wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Greetings,
>
> In light of fairly recent discussion, on this mailing list, I decided
> to investigate the topic of Markdown support for Haddock. The archives
> of the recent discussion can be seen at [1]. This post aims to
> summarise the current state of discussion. I do aim to file a proposal
> for a GSoC project on this issue but it'd be foolish to file a
> proposal for a project aiming to benefit the community without
> consulting the community itself.
>
> Here are some main points and ideas gathered:
> * reSt seems to have a small following - quite a bit smaller than the
> Markdown community. In fact, there seems to be a significant amount of
> people pushing for Markdown which contrasts what we can read in a
> topic from 2008 at [2]. I guess it just shows how much Markdown has
> gained in popularity in recent years.
> * There are issues with using Markdown even before we attempt to use
> it for Haskell documentation:
>   * There exists no formal specification or semantics. It would seem
> that a significant number of Markdown parsers are creating by reverse
> engineering an already existing parser. This is bad because we end up
> propagating the bugs and workarounds around ambiguity that the
> original parser has.
>   * As a follow-up to the previous point, the (vanilla) Markdown is
> ambiguous and there is nothing to resolve it. As Richard A. O'Keefe
> pointed out, there exist situations where it's not possible to infer
> the semantics of Markdown from its official implementation and the
> result is parser/writer-specific [6].
> * John MacFarlane has already written a Markdown parser in Haskell. It
> can be read at [3]. This means that the new extension would not need
> to rely on Pandoc. He says ``I have an experimental thing here that
> could be used as a basis (it's 7x faster than pandoc and uses 1/5 the
> memory, BSD licensed)''. This is great! The post can be seen in full
> at [4].
> * An alternative idea was to simply write a writer module for Pandoc
> for Haddock.
>   * A reader module is already present.
>   * According to John MacFarlane, Haddock is not expressive enough to
> take advantage of this. Furthermore, Pandoc doesn't have some
> constructions that Haddock does [4].
>   * Comes back to the problem on relying on such a large package as
> Pandoc.
> * Yet another proposal was rather than introducing Markdown to
> concentrate on fixing current issues and adding features to Haddock as
> it stands [8]. This is one of the options listed at the short blog
> post at [14] by Johan Tibell.
>   * David Waern, one of Haddock maintainers admits that Haddock lacks
> active development and it has been that way for a longer time. Having
> said that, he seems to believe that Markdown integration is a project
> that can realistically be completed over summer. Such project would be
> able to use the existing HTML backend in Haddock. [9].
> * Math expressions were requested and MathJAX was suggested as a
> solution at [5]. math.stackexchange.com uses MathJAX and it works
> quite well. Personally, I believe that Haskell documentation would
> benefit from this simply due to the academic nature of the language.
> * Support for Literate Haskell would be a welcome addition as
> suggested by Andrew Butterfield at [7].
> * There are issues with CPP and LHS in regards to using Markdown in
> documentation. They are pointed out at [10] by John MacFarlane and
> others that he's replying to.
> * As pointed out 5 years ago at [11], we'd have to do some
> preprocessing on current, fairly critical sections of comments used by
> Haddock. I believe these are fairly useful and it would be a shame to
> see them go.
>
>
> I hope I haven't missed anything of high importance in a list above.
> When researching the topic, issues with Markdown quickly become
> apparent. Today, there are tens of different Markdown flavours: each
> company has different needs and each company interprets the vague
> original documentation in a way that's convenient to them. In these
> situations, topics, e-mails and blog posts like this one happen. There
> is a call to action from October 2012 at [12] but there seems to be
> absolutely no progress on any of the miraculous things mentioned in
> the post. As a result of that post, a W3C community was formed at
> [13]. It's clear that the community is inactive and no progress
> towards a solution was made.
>
> Having considered all information gathered here, I believe this would
> make a good GSoC project. There has been interest in this for Haskell
> since 2008 judging by the size of the last thread, it's clear that the
> community interest is high. In fact, it surprises me that this hasn't
> been done in previous years.
>
> The main issue that I see with using Markdown is the fact that we
> can't simply add a {-# HADDOCK Markdown #-} and let some parser rip
> through it. There are many issues that need to be resolved that I
> outlined above. This will no doubt result in a Markdown flavour suited
> to documenting Haskell rather than the wonderful, standardised
> Markdown that [13] is talking about. Is this different in any way from
> what GitHub or StackOverflow is doing? Introducing yet another
> flavour? In essence, no. For all Haskellers however, there would be a
> difference: this is a chance to use the pleasant-to-eye Markdown that
> many seem to like and use it for documentation. We have the chance to
> formalise it and make it work properly. It's not a perfect solution
> for every single person writing documentation out there but it's a
> good solution for Haskellers. Obviously, the ideal would be to have
> the wonderful, standardised, formalised Markdown that [13] seems to
> try and conjure and then extend that. Alas, we have no such luxury.
>
> As a closing paragraph, I would like to ask some questions.
> - - Is creating yet another Markdown flavour acceptable? I see no better
> solution: we'll have to take Markdown and fix it up to our needs. I'm
> sure most people are aware of the fairly famous Internet web-comic
> relating to standards [15]. We're however not trying to push a new
> standard - writing a proper standard, implementing it and then
> extending it for Haskell documentation is far too much for a single
> summer.
> - - Is there a mentor that would be willing to oversee the project?
> There's a fairly fresh ticket at [16] but there seems to be no
> indication of mentor-ship.
>
> I'm very interested in the project - it seems to hold high value for
> the community while not being completely out of scope for a student
> with a couple of months of Haskell experience, especially considering
> the large ``Getting up to scratch'' period.
>
> Thank you for your time.
>
> Links
> - -----
> [1] - http://comments.gmane.org/gmane.comp.lang.haskell.cafe/104398
> [2] -
> http://www.haskell.org/pipermail/haskell-cafe/2008-February/039846.html
> [3] - https://github.com/jgm/Markdown
> [4] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104421
> [5] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104443
> [6] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104422
> [7] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104428
> [8] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104523
> [9] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104545
> [10] - http://permalink.gmane.org/gmane.comp.lang.haskell.cafe/104444
> [11] -
> http://www.haskell.org/pipermail/haskell-cafe/2008-February/039939.html
> [12] -
> http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
> [13] - http://www.w3.org/community/markdown/
> [14] - http://blog.johantibell.com/2013/04/haskellorg-gsoc-ideas.html
> [15] - http://xkcd.com/927/
> [16] - http://trac.haskell.org/haddock/ticket/244
> - --
> Mateusz K.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
>
> iQIcBAEBAgAGBQJRdt+WAAoJEM1mucMq2pqXspkP/j+SCyfho65/ji5OvNCEBFTb
> YLGC1YY/dk/zbb67gDDxmFtxw/UBGnUifliGUKhCy2Zzm6mwF7BI1U4NWhbR2nkQ
> VWkysqHMn1JM8uQNtkdXEe/KUi2KxcM+VtOkuCUQeF0mlHB7Hthlz58lGZHD+cMK
> EvhN0BGrL1/xnKwSexTSNexXIDCmvCW19jTxuR9uwPqVNVPMjWxO0wRVplnzcqyf
> S8jeG0+Q28S0Su/CxNUdUQ+pE2+FWksNY4a/d/8Tce9sFoTTXUEGAp6Nbgyi+uKd
> yS+AtBqvcsw7KYw03kQAB1qCD05dtc7ptp9ohjgwYY6jzgRMBrIRdDUvmqT6nPh1
> MHgG9rkg9yj+gKhSlNiTZ7MCl/o/CkCtPG0rNtd6//QXDZlH3Xx6CpYKm/GnyAWh
> a2vX5ZX0urVIapFPPEpClMkleLbHfi2UWGVbC43jP0lvsZTMlr4uvwHzJ8N4e9AI
> 2MdK4yZes6b/DSH47FPdoAeYksUvwI0xpI5rpkLuoOh+O094gQVhm4yb+ceqF6CE
> VddqnHPPF4gn7NTeYh6fnsAvzCm5PYgyhEUySbkmlGHjAODtvs6uC9MW4zwYPeCp
> BvGTSsGx7DbtjHwDYQIzMI/oyjFXMVsQ/+bE+pzIo/tQJevXkILaZKYhBvUyAbE5
> ypdJkLdQb8EcWGT5Cx0v
> =sTE0
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130427/829cc297/attachment.htm>