Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-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 midfi...@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@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 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 fuuze...@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 midfi...@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@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 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@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-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@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@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 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 fuuze...@fuuzetsu.co.ukwrote: -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@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@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 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 fuuze...@fuuzetsu.co.ukwrote: 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@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@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@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. -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRgtUoAAoJEM1mucMq2pqXOvkQAJspywchNrrcphMUG6Rnk2pF 0ExpkcVGgbxeGLRBIlH3obi00yWdyPmaei4axbeMSdBB/fKvhb4pVxMKdlwr5mXc x+VAFPOuk5a+3C7FvAd+npkbQJumBGKWhtwKofJe45V8bYIVq+FlSBc/Z/Q4fmbH YFHt/kQy4oEmotxt2Y9BXNw+CNlx7PRMjXTj4I/C4rVjl3KOnna0pM6bJr2KHcp1 wqmDWo4GdoQQRfOkReBInuukZhIo2nfwkMH0NdC89Y4syiKHW4i1x2B7Yedp8H3u dB8H+K5WcX5T4WGzTexAi0yX08KKj11ZJ+d486Io89hmaCR64kMsfmwDpaP9npwX aUTO5dco4YziN5NFYFdM1ol5YgQlGpBMTbSiZQlY+HAHjfS9U04wU/pcijrxmxVh g0m0tbzcHRoEkdC97EsTpxPwjx7HFc8epu9W63bz8Q2Mu4CpxjL2XKl5qtiwfDig HV/v0tnvnH2l0Daz0+6SuFxn3st4H/UV/rnus1ZSb112rMu4XzROKLgyBj4BhRwb l0f+kLNF4dyBmRMuvfA8JG1ZnznN22tL0FDZEgYM+BkSwsyyUC9gEAj8sMFwG7+Y ch2yqxgKEQICFi0ryJanXOvU78ijDNVBgGUi6zDrgX5HySDiZkr4ggDYLGDM989o zxufPmUUXBzVEGlT4KPr =ijHF -END PGP SIGNATURE- ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 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 midfi...@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
I should add that as a consumer of Haddock documentation I can testify that fancier styling (in whatever format) would be of little benefit to _me_. What I need is more plain text and more examples. To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation. So I do agree that markup that doesn't get in the way of a _reader_ who is looking at the source code is an excellent thing. I say this as someone who had to read some Java today and ended up stuffing it through a comment stripper so that I could easily find what I needed to find. This thread is not about the visually lightweight aspect of Markdown. That's a good thing. No argument there. The thread is about how well documented the notation should be. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
I see the pluggable markup being pushed in this thread again. I just want to remind everybody that we currently have a flavor of a markup issue on github. The ghc source code uses literal haskell, and it does not work well on github. http://www.haskell.org/pipermail/ghc-devs/2013-April/001099.html Any markup that is not widely supported makes it harder for third parties to support and parse. The solution is *not* to reimplement github in haskell, but to standardize markup as much as possible. Pluggable markup makes the probability that a github-like service, IDEs and similar can make use of the documentation arbitrarily close to zero. Alexander On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe o...@cs.otago.ac.nzwrote: I should add that as a consumer of Haddock documentation I can testify that fancier styling (in whatever format) would be of little benefit to _me_. What I need is more plain text and more examples. To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation. So I do agree that markup that doesn't get in the way of a _reader_ who is looking at the source code is an excellent thing. I say this as someone who had to read some Java today and ended up stuffing it through a comment stripper so that I could easily find what I needed to find. This thread is not about the visually lightweight aspect of Markdown. That's a good thing. No argument there. The thread is about how well documented the notation should be. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 29 April 2013 18:16, Alexander Kjeldaas alexander.kjeld...@gmail.com wrote: I see the pluggable markup being pushed in this thread again. I just want to remind everybody that we currently have a flavor of a markup issue on github. The ghc source code uses literal haskell, and it does not work well on github. http://www.haskell.org/pipermail/ghc-devs/2013-April/001099.html Any markup that is not widely supported makes it harder for third parties to support and parse. The solution is *not* to reimplement github in haskell, but to standardize markup as much as possible. Pluggable markup makes the probability that a github-like service, IDEs and similar can make use of the documentation arbitrarily close to zero. If it's pluggable, doesn't it make the situation _worse_, as you choose a plug-in that works with one service but then fails for all the others? I think this is a bit of a non-issue: services like github should _not_ mark-up documentation (as you're going to have some kind of issue where it's rendered when you didn't expect it or vice-versa, thus making it different to read the actual code). I tend to agree with Richard, etc.: I'd rather either extend the existing Haddock mark-up or choose a sane markup language if we wish to replace/augment it (I use markup, but find a lot of its conventions appalling). Alexander On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe o...@cs.otago.ac.nz wrote: I should add that as a consumer of Haddock documentation I can testify that fancier styling (in whatever format) would be of little benefit to _me_. What I need is more plain text and more examples. To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation. So I do agree that markup that doesn't get in the way of a _reader_ who is looking at the source code is an excellent thing. I say this as someone who had to read some Java today and ended up stuffing it through a comment stripper so that I could easily find what I needed to find. This thread is not about the visually lightweight aspect of Markdown. That's a good thing. No argument there. The thread is about how well documented the notation should be. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com http://IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Mon, 29 Apr 2013 18:04:47 +1200 Richard A. O'Keefe o...@cs.otago.ac.nz wrote: so that there is no possibility of catching errors early; by definition in that processor there are no errors. Haddock's markup isn't any better in that regard. I spent two hours on my first day with haddock figuring out that I needed an empty comment line before a code block. It didn't issue any warnings or errors either. To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation. Besides fixities, orphan instances, type family instances and partially exported records? It would be beneficial of Haddock to list orphan instances on top of the page. In red. Iff adding markdown doesn't require a major restructuring of haddock, then a GSOC might be better spent adding support for all of these instead; someone else could add markdown later on their own after ML bikeshedding came to some conclusion. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 29/04/2013, at 10:04 PM, kudah wrote: On Mon, 29 Apr 2013 18:04:47 +1200 Richard A. O'Keefe o...@cs.otago.ac.nz wrote: so that there is no possibility of catching errors early; by definition in that processor there are no errors. Haddock's markup isn't any better in that regard. Did I praise Haddock? I spent two hours on my first day with haddock figuring out that I needed an empty comment line before a code block. It didn't issue any warnings or errors either. Report that as a bug. For what it's worth, I've resurrected an old design I did and have been playing with it to see just how bad it really is to use something like @iword than _word_. (Can anyone remember the name of the old formatting program that the * and _ convention comes from? I've got a manual for it buried in a box I can't reach, and I've been trying to remember the name. The manual was a UBC technical report some time in the early 80s, which may mean it was written in BCPL.) I took a thousand line documentation file and converted it to this unambiguous markup with a single reserved character, and the size increase was actually, well, actually, it got @ismaller. I'm not going to describe the notation, because the point is that unambiguous and lightweight are compatible properties. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 30 April 2013 09:28, Richard A. O'Keefe o...@cs.otago.ac.nz wrote: On 29/04/2013, at 10:04 PM, kudah wrote: On Mon, 29 Apr 2013 18:04:47 +1200 Richard A. O'Keefe o...@cs.otago.ac.nz wrote: so that there is no possibility of catching errors early; by definition in that processor there are no errors. Haddock's markup isn't any better in that regard. Did I praise Haddock? I spent two hours on my first day with haddock figuring out that I needed an empty comment line before a code block. It didn't issue any warnings or errors either. Report that as a bug. For what it's worth, I've resurrected an old design I did and have been playing with it to see just how bad it really is to use something like @iword than _word_. Everyone agrees it's useful to have @ilegible markup :) I'm impressed with Mateusz' balanced summary of the issues and look forward to his GSoC project submission about _Markdown_. Conrad. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 28/04/13 00:08, Joe Nash wrote: Managed not to send to all: I think the reason markdown was the original suggestion was due to the fact it is a very widespread and popular syntax, and as Johan commented in the original thread, has to an extent won. Having a consistent, standard documentation syntax for Haskell is of course important, but this project also seeks to standardise the syntax beyond Haskell. I don't think standardising it beyond Haskell is the goal at all. I think that coming up with Markdown that doesn't repeat the mistakes of all the flavours out there is quite difficult in itself, but coming up with such Markdown AND making it making it flexible enough to be of any use with Haddock as is? I think it might be a little out of scope. Extending Haddock itself and providing a writer (and a new reader) for Pandoc will let you write Markdown if you please and then convert it to (and from) many of the formats supported by Pandoc. It may be hedging our bets, as a lot could change and markdown could suddenly fall from fame, but I believe the large variety of opposing markup languages are failing to gain traction in comparison and it is indeed a safe bet. While I don't think it will fall from fame overnight, it would be a shame to restrict people to just using Markdown because that's how all the extensions were implemented. If the flexibility of having it pandoc compatible is a desired feature, can this not be achieved through implementing markdown for haddock as well? Depending on what haddock specific features were required to be added to the superset, it may require only minimal changes to an existing markdown reader/writer in pandoc already. It can, but the restriction comment applies here as well. - -- Mateusz K. -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfPllAAoJEM1mucMq2pqXaKAP/20x2549NvfJgib9oitm1Qn8 CCpGRHdSw4xlIh0pHUE1MKyiJrGGgchuUErN2CJBOKXPhn1fgCWFKJyfOhcPbyr7 2Tpb9t++9G9u0JtIb6/UQpgy6RDXQAqOUs78KxRx3DCb3rYuT5TNpr5ynS58T1+9 7eGQXeUQwhCkKZH6EuIF0qTwxPTsMOAT66oRVnaZJFl2+rOBcw8ZmxMsHnk3bX9t VAR+ySwN4FWce6QZwGU43tMwFHoIxsKrmZ3ZydQPfwdQjJjFjCdTaZhtEYS1Hcvu gg0yU5mjO/1frauqjgC/qo4ez/JrJr5aYHrV91o5S2w0Wl7jfUADAIRDLfhAnTe6 shbiPPBPJeY7EAt6JEytHBmlbwZLyE3zrB0GhlhyaKY344Z5k5Woq2u6zInPx5gi rtiWOUbuerBl8autaKwnPa9i+DSmRwMD8esFIyUMyCbPOMj89YirZtxWGD+ol71i cnBXV8DbX9aYfR8c8U3WNeR8FTOvxKYEC8cc3xErsustrwFlDKzlJD41VGHVZvjB qayuRIR/qMy+fy+8UrxzCFQA32gtZ/ZmjfyHWXHhe2DujThmTi95PtgpLHe1Y2Nh hYuGhj6fqzFvSvSJkE2uWlNPVIu7viBcF1bQEZz07OdYuvU+GbA8OK8q3EzCq+l3 l5uWSedwC4cdyNRxigFS =cgRe -END PGP SIGNATURE- ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 28 Apr 2013 11:33, Mateusz Kowalczyk fuuze...@fuuzetsu.co.uk wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 28/04/13 00:08, Joe Nash wrote: Managed not to send to all: I think the reason markdown was the original suggestion was due to the fact it is a very widespread and popular syntax, and as Johan commented in the original thread, has to an extent won. Having a consistent, standard documentation syntax for Haskell is of course important, but this project also seeks to standardise the syntax beyond Haskell. I don't think standardising it beyond Haskell is the goal at all. I think that coming up with Markdown that doesn't repeat the mistakes of all the flavours out there is quite difficult in itself, but coming up with such Markdown AND making it making it flexible enough to be of any use with Haddock as is? I think it might be a little out of scope. I think my statement was a bit misleading there; I don't mean we should try to come up with a markdown flavour that is suitable for the whole internet to adopt as a standard, that is well beyond scope, as you sat. However, using markdown, even if it has differences and additional peculiarities to make it useful for haddock, is still to an extent bringing haddock in line with the other markdown users and strengthening that standard. Even with the differences there will be more similarities and it will be easier for users to move between other markdown flavours and our flavour than others and haddock syntax. Extending Haddock itself and providing a writer (and a new reader) for Pandoc will let you write Markdown if you please and then convert it to (and from) many of the formats supported by Pandoc. I do really like this idea, and expressed interest in it to John, but it adds additional complexity and dependencies for the documentation writer. Encouraging the writing of more and better documentation means removing as many barriers to doing so as possible, and having to run an additional conversion step to write in a nice syntax may impede that. Having said that, having to write in syntax you don't like also impedes that, so it may in fact encourage the writing of more/better documentation. It may be hedging our bets, as a lot could change and markdown could suddenly fall from fame, but I believe the large variety of opposing markup languages are failing to gain traction in comparison and it is indeed a safe bet. While I don't think it will fall from fame overnight, it would be a shame to restrict people to just using Markdown because that's how all the extensions were implemented. If the flexibility of having it pandoc compatible is a desired feature, can this not be achieved through implementing markdown for haddock as well? Depending on what haddock specific features were required to be added to the superset, it may require only minimal changes to an existing markdown reader/writer in pandoc already. It can, but the restriction comment applies here as well. Does it? If it is suitable to write in another markup and convert to haddock with pandoc, why is it more restrictive to write in another markup and convert to pandoc-markdown? Have I missed a point here? I think these are starting to form two projects with tangential, but slightly differing goals. It would be interesting to see the results if we diverged here and a proposal was submitted for both ideas. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 28/04/13 11:57, Joe Nash wrote: On 28 Apr 2013 11:33, Mateusz Kowalczyk fuuze...@fuuzetsu.co.uk wrote: If the flexibility of having it pandoc compatible is a desired feature, can this not be achieved through implementing markdown for haddock as well? Depending on what haddock specific features were required to be added to the superset, it may require only minimal changes to an existing markdown reader/writer in pandoc already. It can, but the restriction comment applies here as well. Does it? If it is suitable to write in another markup and convert to haddock with pandoc, why is it more restrictive to write in another markup and convert to pandoc-markdown? Have I missed a point here? Extending core Haddock allows us to: 1. Write in any of the Pandoc supported formats, including Markdown 2. Convert it to pure Haddock. This can then be converted back into a different format if need be. Extending Haddock with a Markdown extension allows us to: 1. Write the documentation in any of Pandoc supported formats (including our new Markdown) 2. Convert it from a Pandoc supported format to our Markdown extension as Haddock isn't expressive enough as is to be used. It's a question of being able to go from `Many formats - Pandoc - Many formats' and `Markdown extension - Pandoc - Many formats'. I think these are starting to form two projects with tangential, but slightly differing goals. It would be interesting to see the results if we diverged here and a proposal was submitted for both ideas. I think the goal is still the same: in the end, people will be able to use Markdown to document their code. The means of achieving the goal would give us a different final product that achieves the goal in a slightly different way. - -- Mateusz K. -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfQWCAAoJEM1mucMq2pqXSDYQAJDgstjhoDNctcvbQ6OagkOe TVrJ6V7jmSKHYHsQQziGAeEOmXgZ18UX5TEu5w+ZJ//Yf3zCulhMzAjy+jOqGFPY nOJM5kZL6e7udf/rfmrD8r4GKb3yQAvufJIVLZ8UmMZ3vCAqbOiUs7cKOVcgsoD/ nVs11ySfYfLrF64RGcMqJ6Y9AZMcv05UOOSI3aM++0rj96/34TWRwC5XvQqG08Y+ 8eEB0FZijpKFRwMS8eSrTvCTx93pZkRJpMuHawT19zmylvqoME5WCBkeiXrGUuXE VpYAU5ZZxkW03l65yHb8Ir6IB4kTvD09NprhReR5MRf0J4lbL7TX5WZhP/3APFPk on8gPn4XGqVyn93Y9GplfCCOGr6A1271xEwqOF5YV7Y6NkI/c+SBcPGitgBBE1SO 03BIjr02S9wUtk+Su3szXZ0rmU5/zTLgCAcH2aG1MfbV7tDTKrL6m/J80wjzNULQ nhfHPvqEtT/iH6G2BmyLTSuNUgakDYzA10LPRIuxgoCBaZr9mGcJ6wye/xWx6tud RcuG1a8BS02Xau+zPFKgbdp1UQ8sRW2wiqPsbvwHVMoXvJ1j8ro+Xcxv0+vmar67 tWnYRHH4WgG209j1mX3ssj0gWcFUaFHrPYR9Gpv154NxdOEFq32w9eZO1pXndo8f zW9RmOLRpqh30fX3E2iX =0um2 -END PGP SIGNATURE- ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
I think it's worth backing up here, and remembering the original point of the proposal, by thinking about what is and isn't a goal. I think I'd classify things like this: Goals: - Use a lightweight, common, and familiar core syntax for simple formatting. - Still allow haddock-specific stuff like links to other symbols. Non-Goals: - Compliance/compatibility with any specification or other system. - Have any kind of formal semantics. The essence of this proposal is about making Haddock come closer to matching all the other places where people type formatted text on the Internet. As Johan said, markdown has won. But markdown won because it ended up being a collection of general conventions with compatibility for the 95% of commonly used bits... NOT a formal specification. If there are bits of markdown that are just really, really awkward to use in Haddock, modify them or leave them out. I think the whole discussion is getting off on the wrong start by looking for the right specification against which this should be judged, when it's really just about building the most natural possible ad-hoc adaptation of markdown to documentation comments. Just doing the easy stuff, like switching from /foo/ to *foo* for emphasis, really is most of the goal. Anything beyond that is even better. Compatibility or compliance to a specification are non-issues: no one is going to be frequently copying documentation comments to and from other markdown sources. Haddock will unavoidably have its own extensions for references to other definitions anyway, as will the other system, so it won't be compatible. Let's just accept that. Formal semantics is a non-issue: the behavior will still be defined by the implementation, in that people will write their documentation, and if it looks wrong, they will fix it. We don't want to reason formally about the formatting of our comments, or prove that it's correct. Avoiding unpleasant surprises is good; but avoiding *all* possible ambiguous corner cases in parsing, even when they are less likely than typos, is not particularly important. If some ambiguity becomes a big problem, it will get fixed later as a bug. I think the most important thing here is to not get caught up in debates about advanced syntax or parsing ambiguities, or let that stop us from being able to emphasize words the same way we do in the whole rest of the internet. -- Chris Smith ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 29/04/2013, at 3:26 AM, Chris Smith wrote: I think it's worth backing up here, and remembering the original point of the proposal, by thinking about what is and isn't a goal. I think I'd classify things like this: Goals: - Use a lightweight, common, and familiar core syntax for simple formatting. - Still allow haddock-specific stuff like links to other symbols. Non-Goals: - Compliance/compatibility with any specification or other system. - Have any kind of formal semantics. Why I find the idea of rejecting semantics appalling: Last week I was working with a documentation tool for another language which claims to be Markdown and where *bold* only allows one or more alphabetic words **bold** allows any text _italic_ only allows one or more alphabetic words __italic__ allows any text Today I had to revise some documentation for yet a third language which also claims to be Markdown and where *word* and _word_ both gave italics **word* and __word__ both gave bold. Oh, and the markup wasn't documented, because it was just Markdown, and everyone knows Markdown, right? The syntax I was using was legal syntax, but the semantics was not the semantics I expected and was not written down. I don't care how formal the syntax and semantics are, but I care very much how complete they are. Formal semantics is a non-issue: the behavior will still be defined by the implementation, in that people will write their documentation, and if it looks wrong, they will fix it. Sorry, but this is rubbish. If the semantics is not documented, then people will write their documentation, and it will look wrong, AND THEY WILL NEVER HAVE BEEN GIVEN A CLUE ABOUT WHAT TO WRITE INSTEAD. We don't want to reason formally about the formatting of our comments, or prove that it's correct. Avoiding unpleasant surprises is good; but avoiding *all* possible ambiguous corner cases in parsing, even when they are less likely than typos, is not particularly important. Hmm. Just today, again, looking at the revision list for a Markdown processor, I see comments like This changes the syntax from all previous versions... Code blocks and spans ... will now generate different output... (which reminds me that the author may not be able to fix the looks of their documentation because it may have been perfectly fine when they wrote it, and they may be unavailable when the semantics changes) Tweaked the rules ... this may affect existing content (see above) Sort-of fixed a bug ... Given Markdown's list creation rules, I'm not sure this *can* be fixed. (which is the kind of thing that happens when you decide a clear syntax and semantics are not necessary). If some ambiguity becomes a big problem, it will get fixed later as a bug. As the comment extracted above suggests, it may not be fixable. We may not care about compatibility with other dialects of Markdown, but we should care about compatibility between versions of Haddock. Damn! Why did Watts Humphrey have to die before he'd convinced the world that the cheapest way to fix bugs is to keep them out in the first place? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Sun, Apr 28, 2013 at 6:10 PM, Richard A. O'Keefe o...@cs.otago.ac.nzwrote: Damn! Why did Watts Humphrey have to die before he'd convinced the world that the cheapest way to fix bugs is to keep them out in the first place? I think that much has to do with the historical division in computer science. We have mathematics on the right hand, and electrical engineering on the wrong one. The electrical engineers were unduly influential in the 1960s, 70s, and 80s. The effects of such influence are still being felt. The average software developer thinks that mathematics, with its goody-two-shoes focus on soundness and validity, and all those hard to say words, is /too hard/. And as Kernighan once said, Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it? I've been scoffed at during interviews for saying I solve problems on paper before I start typing! Obviously, names, types, and arrows on recycled printer paper are too clever by half. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Mon, Apr 29, 2013 at 8:42 AM, Alexander Solla alex.so...@gmail.comwrote: I've been scoffed at during interviews for saying I solve problems on paper before I start typing! That has to suck. I hope you're properly avenged when you find work in a savvier, respectful competitor and KICK THEIR ASSES! -- Kim-Ee ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Apr 28, 2013 6:42 PM, Alexander Solla alex.so...@gmail.com wrote: I think that much has to do with the historical division in computer science. We have mathematics on the right hand, and electrical engineering on the wrong one. I've been called many things, but electrical engineer is a new one! My point was not anything at all to do with programming. It was about writing comments, which is fundamentally a communication activity. That makes a difference. It's important to keep in mind that the worst possible consequence of getting corner cases wrong here is likely that some documentation will be confusing because the numbering is messed up in an ordered list. Pointing out that different processors treat markdown differently with respect to bold or italics and such is ultimately missing the point. For example, I an aware that Reddit treats *foo* like italics while, say, Google+ puts it in bold... but I really don't care. What is really of any importance is that both of them take reasonable conventions from plain text and render them reasonably. As far as I'm concerned, you can flip a coin as to whether it ends up in bold or italics. That doesn't mean the choices should not be documented. Sure they should. But it seems ridiculous to sidetrack the proposal to do something nice by concerns about the minutiae of the syntax. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On 29/04/2013, at 4:18 PM, Chris Smith wrote: My point was not anything at all to do with programming. It was about writing comments, which is fundamentally a communication activity. That makes a difference. It's important to keep in mind that the worst possible consequence of getting corner cases wrong here is likely that some documentation will be confusing because the numbering is messed up in an ordered list. The problem is not what it does to the formatting. The problem is what it does to *PEOPLE*. It wastes their time. Suppose there are 10,000 Haskell programmers (I have no idea what the true number of Haskell programmers who like to document is; I hope it's more) and they lose just 6 minutes a day working around glitches in their documentation tools. That's 1000 hours a day; call it 40 days of human life blown away in aggravation every day. To quote Jayne, Where does that get to be fun? Why is it acceptable to waste anyone's time with confusing documentation? Did anyone else read that Markdown-in-Haskell mentioned here recently whose author comments (quoting from memory) any random string of garbage is legal Markdown, so that there is no possibility of catching errors early; by definition in that processor there are no errors. Pointing out that different processors treat markdown differently with respect to bold or italics and such is ultimately missing the point. It may be missing your point, but it hits mine square in the bulls-eye. It wasn't just that they were *different*, it was that the difference wasn't *documented*, and I had to waste an hour of my *LIFE* that I will never get back because some lazy swine couldn't be buggered doing documentation. About a documentation tool. Savour the irony! That doesn't mean the choices should not be documented. Sure they should. If we agree that the semantics should be documented, what are we arguing about? But it seems ridiculous to sidetrack the proposal to do something nice by concerns about the minutiae of the syntax. Nobody is suggesting that the proposal should be *CHANGED*. So talk about sidetrack is unwarranted. The pathetic request from a suffering humanity is that the mark(up/down/sideways) should be *DOCUMENTED* clearly. As for minutiae of the syntax, *you* may call the fact that `` in the middle of a line and `` at the beginning of a line do different things minutiae of the syntax, but *I* call it wantonly squandering my few remaining hours because you think that no or confusing documentation is OK. The more I use Markdown, the better HTML looks. That is, the more effective HTML looks *AS A COMMUNICATION TOOL*, where effectiveness is measured in terms of the effort required to get the result you want. Other people may have other experiences, and that's wonderful. Having better documentation WILL NOT HURT THEM. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
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 fuuze...@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,
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 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. -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfAZrAAoJEM1mucMq2pqX9vgQAKdOnxJgMoT7GpUEyWGZqNt5 2k2yANgjDIcCDcmK+g8B6USTDAV/guDXyLxK6b/gfGYApBqxzyegE/ogxh6zquoq bdaa0BoIQCRsguHy136WX+uwgNH8KN6L684bVpW0960yrtuRK3ow0uklM6wkvQR3 5V8BU7vhKyVxldgEkPQMLMI+u8ppVDUp6RUW/7EQctunmgWwzaO3LMhrc8eBjumc saee0SR9yUlpFq8zEQIw+EGqsokY5lPbbhfUJwDYbqtm/LRgL5rw+NhptIf1GgFm hGvLqsUsdRRLx5GH/FN2PoQNt4xnqjoPEOXL60p5SYtBvDmfFOFkJ+1oGCrM0JLl Yy4BtcXJpRxFEaWYq/TGaDWdIRSpRZ2JvSwlnHW+EpnXKnPVnReKOzIa4iPD94qS WdX+uK/v6ikmRbht1rkNvV3a+oWYpwx7dIhk+XzcMKxsb1DJ5bmI2/SxfhARcWxJ zXhhYJSB/TpsvPAlKcT3emLJUwaigxr59JxlDmnq9goYl/MZVZDe4ihCH8JwC/hE oHrG7TL5HPLxWjiJ/cmyOsoVgcwgu0SxH4vsHqtFs66uYZ1gPahw6ILJlS0y3lbb XH9w4dkZybXUYPohD5ZZZXtWTKP+xGGNPdvC8D2K0yYNDTXBvXhl9R6S+oBRFIZs G/VgHSOw3givgsrQT+BZ =vZF9 -END PGP SIGNATURE- ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley alist...@abayley.orgwrote: 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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Markdown extension for Haddock as a GSoC project
Oops, forgot to reply all. -- Forwarded message -- From: Chris Smith cdsm...@gmail.com Date: Apr 27, 2013 12:04 PM Subject: Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project To: Bryan O'Sullivan b...@serpentine.com Cc: I don't agree with this at all. Far more important than which convention gets chosen is that Haskell code can be read and written without learning many dialects of Haddock syntax. I see an API for pluggable haddock syntax as more of a liability than a benefit. Better to just stick to what we have than fragment into more islands. I do think that changing Haddock syntax to include common core pieces of Markdown could be a positive change... but not if it spawns a battle of fragmented documentation syntax that lasts a decade. On Apr 27, 2013 11:08 AM, Bryan O'Sullivan b...@serpentine.com wrote: On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley alist...@abayley.orgwrote: 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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 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 alist...@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
On Sat, Apr 27, 2013 at 1:47 PM, Ben midfi...@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
I agree with Chris that it would be better to have a standard syntax for Haskell documentation. Especially if the alternative is ten different markup languages. (Remember, all of these need to be supported in haddock, which is a basic piece of infrastructure.) Here's a thought. Instead of adding support for markdown, why not enhance the existing haddock markup, making it more expressive, so that it could encode the same range of structural features as markdown? If this were done, we could add a haddock writer to pandoc. There is already a haddock reader in the development version, but a writer is difficult because haddock is so much less expressive than other formats. For example, unless I'm mistaken, it doesn't allow list items with multiple paragraphs or other block elements, or nested lists, or images, or blockquotes. With a pandoc reader and writer for haddock, it would be easy to write your documentation in any format you choose (several variants of markdown, reST, textile, LaTeX, HTML, mediawiki) and produce equivalent haddock markup to paste into the source file. It would also be easy to convert the documentation in your source file to any of the formats supported by pandoc. So, you could generate a man page from your haddock markup, or a web page or blog entry, or a LaTeX document. It seems to me that this would provide most of the advantages people who want a markdown extension for haddock are looking for. But it would not require taking sides in markdown/reST/asciidoc/creole wars, and it would not lead to the fragmentation of documentation formats in Haskell source code. If the extensions to haddock markup were done carefully, it wouldn't even require a special PRAGMA, since all existing markup would have the same interpretation in the extended markup. John +++ Chris Smith [Apr 27 13 12:05 ]: I don't agree with this at all. Far more important than which convention gets chosen is that Haskell code can be read and written without learning many dialects of Haddock syntax. I see an API for pluggable haddock syntax as more of a liability than a benefit. Better to just stick to what we have than fragment into more islands. I do think that changing Haddock syntax to include common core pieces of Markdown could be a positive change... but not if it spawns a battle of fragmented documentation syntax that lasts a decade. On Apr 27, 2013 11:08 AM, Bryan O'Sullivan [3]b...@serpentine.com wrote: On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley [4]alist...@abayley.org wrote: How's about Creole? [5]http://wikicreole.org/ Found it via this: [6]http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favo urite-language/ If you go with Markdown, I vote for one of the Pandoc implementations, probably Pandoc (strict): [7]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 [8]Haskell-Cafe@haskell.org [9]http://www.haskell.org/mailman/listinfo/haskell-cafe References 1. mailto:cdsm...@gmail.com 2. mailto:b...@serpentine.com 3. mailto:b...@serpentine.com 4. mailto:alist...@abayley.org 5. http://wikicreole.org/ 6. http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/ 7. http://johnmacfarlane.net/babelmark2/ 8. mailto:Haskell-Cafe@haskell.org 9. http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Markdown extension for Haddock as a GSoC project
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 27/04/13 22:18, John MacFarlane wrote: I agree with Chris that it would be better to have a standard syntax for Haskell documentation. Especially if the alternative is ten different markup languages. (Remember, all of these need to be supported in haddock, which is a basic piece of infrastructure.) Here's a thought. Instead of adding support for markdown, why not enhance the existing haddock markup, making it more expressive, so that it could encode the same range of structural features as markdown? If this were done, we could add a haddock writer to pandoc. There is already a haddock reader in the development version, but a writer is difficult because haddock is so much less expressive than other formats. For example, unless I'm mistaken, it doesn't allow list items with multiple paragraphs or other block elements, or nested lists, or images, or blockquotes. With a pandoc reader and writer for haddock, it would be easy to write your documentation in any format you choose (several variants of markdown, reST, textile, LaTeX, HTML, mediawiki) and produce equivalent haddock markup to paste into the source file. It would also be easy to convert the documentation in your source file to any of the formats supported by pandoc. So, you could generate a man page from your haddock markup, or a web page or blog entry, or a LaTeX document. It seems to me that this would provide most of the advantages people who want a markdown extension for haddock are looking for. But it would not require taking sides in markdown/reST/asciidoc/creole wars, and it would not lead to the fragmentation of documentation formats in Haskell source code. If the extensions to haddock markup were done carefully, it wouldn't even require a special PRAGMA, since all existing markup would have the same interpretation in the extended markup. John ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe I was under the impression that Markdown specifically was requested due to its high popularity, ease of writing and being very readable to a human. As you mention, currently Haddock is not expressive enough to have a writer and would need extending first. The advantages of extending Haddock this way are obvious: people write the documentation in whatever they want and then use Pandoc to convert it to a format they want to distribute in. I'm unsure however whether such an extension is strictly a good thing: what's more readable in source: Haddock with even more stuff tacked on or Markdown with some already present Haddock constructs? There are a fair few complaints about how unwieldy Haddock currently is and I'm worried that extending it for the sake of (a really nice) ability of conversion between formats with Pandoc might make it even more unwieldy. Yes, you can write the docs in any of the billion formats Pandoc supports and then convert it but many people simply want to write docs right into their source files, right as they write actual code without reliance on external tools -- something Markdown would excel at if implemented. So in the end, it just comes down to to what the community _really_ wants: more expressive core Haddock with ability to convert between the formats or yet another Markdown flavour tacked onto Haddock as an extension. It should be noted that this would probably end up serving as a basis for the Pandoc module anyway so why duplicate the effort? Pandoc already handles Markdown, as Christopher Howard pointed out. Discussion on the topic will is most welcome. I am one of the students interested in this project and I have already written a draft proposal with the idea of implementing Markdown as an extension because that's what it seems the community wanted in previous threads and discussions. Is this _really_ what we want though? Personally, I think the benefits of extending Haddock itself and writing a writer module for Pandoc not only cover everything a new, Haskell specific Markdown could do but provide even greater flexibility. I'd also prefer to work on extending Haddock rather than just tacking an extension to it that might not get used because some people might dislike Markdown and would miss out on any new features. The SoC proposal deadlines are on 3rd of May so it'd be great to hear some opinions on this within the next 3 days or so, after which point I will adjust my proposal accordingly, cross my fingers and hope for the best ;) - -- Mateusz K. -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfFXcAAoJEM1mucMq2pqX8kkQAI+xRwMOVsq9T14bKLZ3Wiv7 citbn/hWDYSC8zpSnFIGW87On9/phBIhXaBA5F878mao0AAOMmN0S2ZfcTusaRjk zXm2Dfof6ZKa38xTTjcoBuNWvv7mNwY8592krRPKden2if+II+2bXEd8kqSOX2zi JibaTlXE1ud8sKiUB9hMlE+dcYm3J/G5FJqTFJv45kX2XeApni7J4/4M6ST0X/8z
[Haskell-cafe] Markdown extension for Haddock as a GSoC project
-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
