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