Mateusz Kowalczyk | 23 Apr 21:23 2013
Picon

Markdown extension for Haddock as a GSoC project


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
(Continue reading)

Alistair Bayley | 27 Apr 11:23 2013

Re: Markdown extension for Haddock as a GSoC project

How's about Creole?

Found it via this:

If you go with Markdown, I vote for one of the Pandoc implementations, probably Pandoc (strict):

(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

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Mateusz Kowalczyk | 27 Apr 19:10 2013
Picon

Re: Markdown extension for Haddock as a GSoC project


On 27/04/13 10:23, Alistair Bayley wrote:
> 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

I'd very much like to avoid creating yet another Markdown flavour but
I don't think it will be possible to use an existing one in its entirety.
The issue (?) with Creole is [1], where you're allowed to tack on
anything you want in the parts not covered in the spec. If you ask me,
this sounds exactly like what the case was with the original
`specification' of Markdown: the documentation was just too damn vague
and ambiguous so we ended up with every company interpreting it
themselves in a way that was favourable to them.

Is there any reason in particular why you'd like Pandoc (strict)
Markdown rather than any other flavour?

--

-- 
Mateusz K.
Bryan O'Sullivan | 27 Apr 20:06 2013

Re: Markdown extension for Haddock as a GSoC project

On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley <alistair <at> abayley.org> wrote:
How's about Creole?

Found it via this:

If you go with Markdown, I vote for one of the Pandoc implementations, probably Pandoc (strict):

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

Probably the best way to deal with this is by sidestepping it: make the support for alternative syntaxes as modular as possible, and choose two to start out with in order to get a reasonable shot at constructing a suitable API.

I think it would be a shame to bikeshed on which specific syntaxes to support, when a lot of productive energy could more usefully go into actually getting the work done. Better to say "prefer a different markup language? code to this API, then submit a patch!"
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Ben | 27 Apr 22:47 2013
Picon

Re: Markdown extension for Haddock as a GSoC project

asciidoc has been mentioned a few times in comments, i think it's worth looking at.  

* mature, over 10 years old (predates markdown i think), not "just another markdown clone"
* human readable, but it has a lot of advanced features including mathematical formulas.  
* github supports it (they were sufficiently impressed with it to make a ruby implementation called asciidoctor)
* several o'reilly books have been written in it, and the git documentation is written in it.

roughly, asciidoc is to docbook as markdown is to html.  i'm no expert in this area but it seems to be a good alternative.

http://asciidoc.org/
http://asciidoctor.org/docs/what-is-asciidoc-why-use-it/

best, ben

On Apr 27, 2013, at 11:06 AM, Bryan O'Sullivan wrote:

> On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley <alistair <at> abayley.org> wrote:
> 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...)
> 
> Probably the best way to deal with this is by sidestepping it: make the support for alternative syntaxes as
modular as possible, and choose two to start out with in order to get a reasonable shot at constructing a
suitable API.
> 
> I think it would be a shame to bikeshed on which specific syntaxes to support, when a lot of productive
energy could more usefully go into actually getting the work done. Better to say "prefer a different
markup language? code to this API, then submit a patch!"
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
Bryan O'Sullivan | 27 Apr 23:02 2013

Re: Markdown extension for Haddock as a GSoC project

On Sat, Apr 27, 2013 at 1:47 PM, Ben <midfield <at> gmail.com> wrote:
asciidoc has been mentioned a few times in comments, i think it's worth looking at.

This is the problem I was afraid of: for every markup syntax under the sun, someone will come along to champion it.

The choice of one or N syntaxes is ultimately up to the discretion of the student, guided by their mentor. It is in our collective interest to avoid prolonging a bikeshed discussion on this, as a long inconclusive discussion risks dissuading any sensible student or mentor from wanting to pursue the project in the first place.
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Ben | 2 May 07:57 2013
Picon

Re: Markdown extension for Haddock as a GSoC project

sorry, i was only trying to make a helpful suggestion!

just to clarify: i'm not championing asciitext (or any other format) -- i only heard about it recently in a
comment on

http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html

i checked it out and it sounded cool, so i thought it'd be a helpful pointer to whomever is working on new
haddock -- they are of course welcome to ignore it.  totally understand that overmuch debate is not helpful
(though i'm not sure it's fair to call it bikeshedding, since it is a primary feature of the proposed project!)

best, ben

On Apr 27, 2013, at 2:02 PM, Bryan O'Sullivan wrote:

> On Sat, Apr 27, 2013 at 1:47 PM, Ben <midfield <at> gmail.com> wrote:
> asciidoc has been mentioned a few times in comments, i think it's worth looking at.
> 
> This is the problem I was afraid of: for every markup syntax under the sun, someone will come along to
champion it.
> 
> The choice of one or N syntaxes is ultimately up to the discretion of the student, guided by their mentor. It
is in our collective interest to avoid prolonging a bikeshed discussion on this, as a long inconclusive
discussion risks dissuading any sensible student or mentor from wanting to pursue the project in the
first place.
Mateusz Kowalczyk | 2 May 08:47 2013
Picon

Re: Markdown extension for Haddock as a GSoC project


On 02/05/13 06:57, Ben wrote:
> sorry, i was only trying to make a helpful suggestion!
> 
> just to clarify: i'm not championing asciitext (or any other
> format) -- i only heard about it recently in a comment on
> 
> http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
>
>  i checked it out and it sounded cool, so i thought it'd be a
> helpful pointer to whomever is working on new haddock -- they are
> of course welcome to ignore it.  totally understand that overmuch
> debate is not helpful (though i'm not sure it's fair to call it
> bikeshedding, since it is a primary feature of the proposed
> project!)
> 
> best, ben
> 
> On Apr 27, 2013, at 2:02 PM, Bryan O'Sullivan wrote:
> 
>> On Sat, Apr 27, 2013 at 1:47 PM, Ben <midfield <at> gmail.com> wrote: 
>> asciidoc has been mentioned a few times in comments, i think it's
>> worth looking at.
>> 
>> This is the problem I was afraid of: for every markup syntax
>> under the sun, someone will come along to champion it.
>> 
>> The choice of one or N syntaxes is ultimately up to the
>> discretion of the student, guided by their mentor. It is in our
>> collective interest to avoid prolonging a bikeshed discussion on
>> this, as a long inconclusive discussion risks dissuading any
>> sensible student or mentor from wanting to pursue the project in
>> the first place.
> 
> 
> _______________________________________________ Haskell-Cafe
> mailing list Haskell-Cafe <at> haskell.org 
> http://www.haskell.org/mailman/listinfo/haskell-cafe
> 
These two posts are exactly why I believe that extending Haddock
itself would be of more benefit than simply adding a Markdown
extension to it: with addition to core features, integrating any of
the N syntaxes that people want suddenly becomes the question of just
writing reader and writer modules for Pandoc instead of a full project
on marshalling yet another markup as an extension directly to Haddock.

--

-- 
Mateusz K.
Petr Pudlák | 2 May 10:14 2013
Picon

Re: Markdown extension for Haddock as a GSoC project

Hi,

It seems that during the recent suggestions about what markup to choose (Markdown, Creole, Asciidoc, etc.), we've forgotten about one of the goals that seem very important to me for Haskell: the ability to write math formulas. I have experienced on StackExchange that just adding MathJAX to Markdown leads to many surprising errors that can be fixed only by strange hacks.

Personally I'd incline to choose some existing, well-established markup language with formal specification that supports math (hopefully there is one). Extending Haddock with new features and a syntax for math formulas would certainly require to design such a specification, which isn't easy, and using an existing one would simplify the process a lot. Also I believe that newcomers to Haskell would definitely appreciate working with an existing markup language (and I'm sure not only them) instead of having to learn Haddock's syntax.

  Best regards,
  Petr



2013/5/2 Mateusz Kowalczyk <fuuzetsu <at> fuuzetsu.co.uk>
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 02/05/13 06:57, Ben wrote:
> sorry, i was only trying to make a helpful suggestion!
>
> just to clarify: i'm not championing asciitext (or any other
> format) -- i only heard about it recently in a comment on
>
> http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
>
>  i checked it out and it sounded cool, so i thought it'd be a
> helpful pointer to whomever is working on new haddock -- they are
> of course welcome to ignore it.  totally understand that overmuch
> debate is not helpful (though i'm not sure it's fair to call it
> bikeshedding, since it is a primary feature of the proposed
> project!)
>
> best, ben
>
> On Apr 27, 2013, at 2:02 PM, Bryan O'Sullivan wrote:
>
>> On Sat, Apr 27, 2013 at 1:47 PM, Ben <midfield <at> gmail.com> wrote:
>> asciidoc has been mentioned a few times in comments, i think it's
>> worth looking at.
>>
>> This is the problem I was afraid of: for every markup syntax
>> under the sun, someone will come along to champion it.
>>
>> The choice of one or N syntaxes is ultimately up to the
>> discretion of the student, guided by their mentor. It is in our
>> collective interest to avoid prolonging a bikeshed discussion on
>> this, as a long inconclusive discussion risks dissuading any
>> sensible student or mentor from wanting to pursue the project in
>> the first place.
>
>
> _______________________________________________ Haskell-Cafe
> mailing list Haskell-Cafe <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
These two posts are exactly why I believe that extending Haddock
itself would be of more benefit than simply adding a Markdown
extension to it: with addition to core features, integrating any of
the N syntaxes that people want suddenly becomes the question of just
writing reader and writer modules for Pandoc instead of a full project
on marshalling yet another markup as an extension directly to Haddock.

- --
Mateusz K.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQIcBAEBAgAGBQJRggwfAAoJEM1mucMq2pqXHmAP/R2nHmXiNHDVqWEAoLQHSNeC
psgcNm2hAclo6AxYprPsNHkqIUYh4HVpsc8FZw+RsAwkpUrGiaaMD/OTNB5857V+
296lzHNOLNvge7B77FfVTa5wx1j2M+N0+pcOzcxr8qX5opfJNOcMPPtaXqD0nMS7
6EsBac/pQAjOHVYOTHEpsxAbl70s/QFBa/kW6tZPJmWKdHp6c3VmL5qx9CY9lZO4
1QKmyKqQMhxN0hmxcFHcYsa/IsohSAFewrs6JDErShn5ffIvtkhEM0UKVCBM26G4
Eu4Hadrv/AyoDT6UdtMgVllzY0XrykfLJ1nXzpp0QklYml0/SMmNrwqO9wfooMfF
XKWiW2T8QWN5dFJO4kM9JA6UqpQ2uvrK6qWREL3jv8/jbEvg0WVko3zTW/BNzjF2
/Pn/9Z1vxYEee4A3Oa0sT7NGhKqK9KRtIgdfuXvTCnctvFYBxwtGHCcKuxgHVNNM
GIJAqMtUtwr1Kjt37Gf0F+r1TBQfOsJL7tzRPayZKYPl7uA/ugrHHnYxL5JqIyAq
bMUqLxAsDNW2tXIPzmNi4QYPqaopaUmwAD8IPvFk9e/1vI0QnU8b1URLjt5zl3O+
mFyWYTQd/UuaFOmOEmfLMJz+n2tRqL51LOCYcHwEjpH10WuTpX1DS3LWErcwppO5
bUZggQ5DwewgRIfCNEfS
=nnP/
-----END PGP SIGNATURE-----

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Andrew Butterfield | 2 May 10:26 2013
Picon
Picon

Re: Markdown extension for Haddock as a GSoC project

My 2c (before such coins disappear...)

On 2 May 2013, at 09:14, Petr Pudlák wrote:

Hi,


Personally I'd incline to choose some existing, well-established markup language with formal specification that supports math (hopefully there is one).

So TeX/LaTeX is out then  .... :-(



--------------------------------------------------------------------
Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
Lero <at> TCD, Head of Foundations & Methods Research Group
Director of Teaching and Learning - Undergraduate,
School of Computer Science and Statistics,
Room G.39, O'Reilly Institute, Trinity College, University of Dublin
                          http://www.scss.tcd.ie/Andrew.Butterfield/
--------------------------------------------------------------------

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Mateusz Kowalczyk | 2 May 10:46 2013
Picon

Re: Markdown extension for Haddock as a GSoC project


On 02/05/13 09:26, Andrew Butterfield wrote:
> My 2c (before such coins disappear...)
> 
> On 2 May 2013, at 09:14, Petr Pudlák wrote:
> 
>> Hi,
>> 
>> 
>> Personally I'd incline to choose some existing, well-established
>> markup language with formal specification that supports math
>> (hopefully there is one).
> 
> So TeX/LaTeX is out then  .... :-(
> 
> 
> 
> --------------------------------------------------------------------
>
> 
Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
> Lero <at> TCD, Head of Foundations & Methods Research Group Director of
> Teaching and Learning - Undergraduate, School of Computer Science
> and Statistics, Room G.39, O'Reilly Institute, Trinity College,
> University of Dublin http://www.scss.tcd.ie/Andrew.Butterfield/ 
> --------------------------------------------------------------------
>
> 
> 
> 
> 
> _______________________________________________ Haskell-Cafe
> mailing list Haskell-Cafe <at> haskell.org 
> http://www.haskell.org/mailman/listinfo/haskell-cafe
> 

With a reader and write module for new Haddock, you should be able to
write LaTeX and convert that to Haddock and vice-versa. Some kind of
Markdown was requested by popular demand but if we end up going the
Pandoc way, we'll end up getting the plethora of already supported
formats basically for free.
--

-- 
Mateusz K.
Carter Schonwald | 2 May 21:52 2013
Picon

Re: Markdown extension for Haddock as a GSoC project

indeed. That approach seems like the most likely to be successful within the scope of a single summer.

That said, this does raise the question of what needs to be fixed up / added to the  haddock grammar to 
a) make it a rich target for pandoc
b) make sure the augmented haddock grammar is human friendly and we can give helpful syntax errors etc.

Whats the status of this proposal for this years GSOC? Done well / right, it'd be super valuable for the community

-Carter 


On Thu, May 2, 2013 at 4:46 AM, Mateusz Kowalczyk <fuuzetsu <at> fuuzetsu.co.uk> wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 02/05/13 09:26, Andrew Butterfield wrote:
> My 2c (before such coins disappear...)
>
> On 2 May 2013, at 09:14, Petr Pudlák wrote:
>
>> Hi,
>>
>>
>> Personally I'd incline to choose some existing, well-established
>> markup language with formal specification that supports math
>> (hopefully there is one).
>
> So TeX/LaTeX is out then  .... :-(
>
>
>
> --------------------------------------------------------------------
>
>
Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
> Lero <at> TCD, Head of Foundations & Methods Research Group Director of
> Teaching and Learning - Undergraduate, School of Computer Science
> and Statistics, Room G.39, O'Reilly Institute, Trinity College,
> University of Dublin http://www.scss.tcd.ie/Andrew.Butterfield/
> --------------------------------------------------------------------
>
>
>
>
>
> _______________________________________________ Haskell-Cafe
> mailing list Haskell-Cafe <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>

With a reader and write module for new Haddock, you should be able to
write LaTeX and convert that to Haddock and vice-versa. Some kind of
Markdown was requested by popular demand but if we end up going the
Pandoc way, we'll end up getting the plethora of already supported
formats basically for free.
- --
Mateusz K.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQIcBAEBAgAGBQJRgifxAAoJEM1mucMq2pqXtS0P/Rxx/JHS0vprqi0oCVDPcVTG
0ZCzptgVUYGlbVfdJYsbFChC+7SjWnb6/AXlsEfVnwhpVTparlwRdWu11+LxWWaH
sHWqWX6mHk236rBcxllbpE92u/WqOcn4YsOLArClz8xbTVw2YkUHzFUBnnSGvClS
V7Qq2jf0xnJWzPcFw1WY9/UdIhcOUif526VW41pkggXCzxp6/gr2VtKJbWJ/ljHX
YCdrRRZXypT9UZKKt1oeKWp+XCs5Oh6nBZuJNNTeBQo03wyap4SYrnDlAnhPu911
Fb8+eqGTJKDsKIstERwgWfVSO/qzWUfOTc0orsvJHvy9SCATGKNkwRIvWX2SZj12
bl1D1Z0YQhHl3yRb2G7ZZXGcC6GXfAMk9/I/tgu74HtqM0hxHvZwGwPCX0Ql30EU
GJsVBgabv8v6TS96/iipRTZTAUphqSTopl/JWhg0n+p5OVtZKOu/OI/xefmgqI26
Hx1I4yZKDMHkzYJFYhoi9QBLy+XzwlRctjNcEZClse+St1hlgR6lLLjhLHJQoRDg
V5TWkzkaO3SvrnKFeObaRdt/Q8BxNgfOcWqyLcioobbu4Un0j6ncpcHZnAFHF0i7
FkE0CGxMiwLrB9F8sw+VTgFnCk3xm0QwgfpDeQVifhD83Jk51pJc8L/vg63ANEGN
FI4KKji7k/J2NbfQHxDG
=2xQm
-----END PGP SIGNATURE-----

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Mateusz Kowalczyk | 2 May 23:05 2013
Picon

Re: Markdown extension for Haddock as a GSoC project


On 02/05/13 20:52, Carter Schonwald wrote:
> indeed. That approach seems like the most likely to be successful
> within the scope of a single summer.
> 
> That said, this does raise the question of what needs to be fixed
> up / added to the  haddock grammar to a) make it a rich target for
> pandoc b) make sure the augmented haddock grammar is human friendly
> and we can give helpful syntax errors etc.
> 
> Whats the status of this proposal for this years GSOC? Done well /
> right, it'd be super valuable for the community
> 
> -Carter
> 
> 
> On Thu, May 2, 2013 at 4:46 AM, Mateusz Kowalczyk 
> <fuuzetsu <at> fuuzetsu.co.uk>wrote:
> 
> On 02/05/13 09:26, Andrew Butterfield wrote:
>>>> My 2c (before such coins disappear...)
>>>> 
>>>> On 2 May 2013, at 09:14, Petr Pudlák wrote:
>>>> 
>>>>> Hi,
>>>>> 
>>>>> 
>>>>> Personally I'd incline to choose some existing,
>>>>> well-established markup language with formal specification
>>>>> that supports math (hopefully there is one).
>>>> 
>>>> So TeX/LaTeX is out then  .... :-(
>>>> 
>>>> 
>>>> 
>>>> --------------------------------------------------------------------
>>>>
>>>>
>
>>>> 
Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
>>>> Lero <at> TCD, Head of Foundations & Methods Research Group
>>>> Director of Teaching and Learning - Undergraduate, School of
>>>> Computer Science and Statistics, Room G.39, O'Reilly
>>>> Institute, Trinity College, University of Dublin
>>>> http://www.scss.tcd.ie/Andrew.Butterfield/ 
>>>> --------------------------------------------------------------------
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> 
_______________________________________________ Haskell-Cafe
>>>> mailing list Haskell-Cafe <at> haskell.org 
>>>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>>> 
> 
> With a reader and write module for new Haddock, you should be able
> to write LaTeX and convert that to Haddock and vice-versa. Some
> kind of Markdown was requested by popular demand but if we end up
> going the Pandoc way, we'll end up getting the plethora of already
> supported formats basically for free.
>> 
>> _______________________________________________ Haskell-Cafe
>> mailing list Haskell-Cafe <at> haskell.org 
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>> 
> 
Last time I checked, there are two proposals filed for this. One, to
extend Haddock with features that have been long missing and extend it
with things like GADTs etc. Then implement a Markdown notation
alongside it.

The other one is to extend Haddock to be... compatible with Pandoc and
writing the modules. Only then, if time allows, any new extended
features will be put in.

Both effectively reach the goal of allowing Markdown but the first one
provides support for just Markdown and now the ability to write the
Pandoc modules if desired while the second one provides support for
whatever formats Pandoc currently works with and allows for feature
extensions from that point.

I think that if more time was given and both projects were worked on
independently, they would eventually reach the same level of features.
--

-- 
Mateusz K.

Gmane