Re: [Haskell-cafe] Haddock GSOC project progress
Why not use uu-parsinglib, which will tell you what is wrong and nevertheless will continue parsing? Currently Jacco Krijnen is working on an extensible version of Pandoc, based on the AspectAG and the Murder packages, so you can define your own plugins for syntax and semantics. Doaitse Swierstra On Aug 1, 2013, at 1:14 , Richard A. O'Keefe o...@cs.otago.ac.nz wrote: On 31/07/2013, at 8:16 PM, Simon Hengel wrote: * There is no such thing as a parse error in Markdown, and I think we should try to make this true for Haddock markup, too It is very far from clear that this is a virtue in Markdown. In trying to learn Markdown, I found it an excessively tiresome defect. Whenever I was trying to learn how to produce some combination of effects, instead of Markdown telling me at THIS point you had something I wasn't expecting, it would just produce incorrect output, defined as anything other than what I intended. It also meant that two different Markdown processors would accept the same text silently but do different things with it. This is one of the reasons I won't use Markdown. ___ 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] Haddock GSOC project progress
On 31/07/13 06:37, Roman Cheplyaka wrote: Hi Mateusz, This looks great — I'm especially excited about List entries no longer have to be separated by empty lines! Glad to hear that. However, the decision to use Attoparsec (instead of Parsec, say) strikes me as a bit odd, Parsec has a dependency on Data.Text that you can't easily get rid of. With Attoparsec, I was able to simply get rid of the modules I was not interested in (anything with Text) and only keep the ByteString part. as it wasn't intended for parsing source code. We're not parsing source code. As I mention, we get comment content out from GHC and parse the markup there. In particular, I'm concerned with error messages this parser would produce. Currently there exist only two error messages: one for when module header parsing fails and another one for when parsing of anything else fails. Currently the parsing functions have the type ‘DynFlags - String - Maybe (Doc RdrName)’ and if we get out Nothing then you get a generic error message and no guidance. This is also the current behaviour. Now, I agree that this sounds horrible BUT in actuality, there's not much information we could ever give. This isn't the case of inability to do so: I could simply add a (| fail error message) to relevant parts and it would get propagated up. The reason why I said that this isn't much of a problem is because there are very few cases where parsing actually can fail: in most cases if your markup isn't valid semantically, it's probably valid syntactically as a regular string. I mention in my post that we will now accept a bit wider range of syntax. In the past, this: some text exampleExpression result would fail and you would get the unhelpful error messages. With the new parser this will simply be accepted as a regular string. In fact, I actually can't think of a comment that would result in parse error with the new parser. Just to check, I just ran 500 randomly generated strings using QuickCheck through each of the two parsing functions exposed to the rest of the program and none of them caused a parse error. It's up to the developer to visually inspect that their markup produced what they wanted – we can't read minds (and frankly, the rules are fairly simple). Roman * Mateusz Kowalczyk fuuze...@fuuzetsu.co.uk [2013-07-30 23:35:45+0100] Greetings cafe, As some of you might know, I'm hacking on Haddock as part of Google Summer of Code. I was recently advised to create a blog and document some of what I have been doing recently. You can find the blog at [1] if you're interested. The first post goes over the work from the last month or so. Future posts should be shorter and on more specific topics. There's an overview of what has happened/changed/will change at the bottom of the post if you're short on time. Thanks. [1] - http://fuuzetsu.co.uk/blog I would also like to take this opportunity to say that there is one more change that I forgot to mention. Obviously invalid strings between double quotes will no longer be treated as module names and blindly linked. The checking will only be on the syntax of the string so it will still create hyperlinks to syntactically valid module names that might not actually exist. -- Mateusz K. 0x2ADA9A97.asc Description: application/pgp-keys ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSOC project progress
Is Data.Text as an extra dependency really that bad? Remember that you are parsing comments, prose, human produced text, where Data.Text is way more useful than ByteString. -- Mats Rauhala MasseR ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSOC project progress
On 31/07/13 08:21, Mats Rauhala wrote: Is Data.Text as an extra dependency really that bad? Remember that you are parsing comments, prose, human produced text, where Data.Text is way more useful than ByteString. It has to come with GHC boot packages and it currently doesn't. I have updated my post accordingly to mention it. ByteString indeed has its problems (I have to be quite careful to make sure unicode doesn't get mangled) but that's just how it is at the moment. If Text ever makes it in, the transition will be trivial. We're not doing anything fancy to the text we get out anyway so any performance difference it might bring is negligable. The only difference I can think of would be that we would no longer have to worry about preserving unicode by hand. It's an inconvenience, but that's about it. Nothing mission-critical. -- Mateusz K. 0x2ADA9A97.asc Description: application/pgp-keys ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSOC project progress
Hi Roman, However, the decision to use Attoparsec (instead of Parsec, say) strikes me as a bit odd, as it wasn't intended for parsing source code. In particular, I'm concerned with error messages this parser would produce. In addition to what Mateusz already said, I want to briefly summarize my justification for using Attoparsec: * Attoparsec's backtracking behavior is much easier to work with than Parsec's * There is no such thing as a parse error in Markdown, and I think we should try to make this true for Haddock markup, too Cheers, Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSOC project progress
On 31/07/2013, at 8:16 PM, Simon Hengel wrote: * There is no such thing as a parse error in Markdown, and I think we should try to make this true for Haddock markup, too It is very far from clear that this is a virtue in Markdown. In trying to learn Markdown, I found it an excessively tiresome defect. Whenever I was trying to learn how to produce some combination of effects, instead of Markdown telling me at THIS point you had something I wasn't expecting, it would just produce incorrect output, defined as anything other than what I intended. It also meant that two different Markdown processors would accept the same text silently but do different things with it. This is one of the reasons I won't use Markdown. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Haddock GSOC project progress
Greetings cafe, As some of you might know, I'm hacking on Haddock as part of Google Summer of Code. I was recently advised to create a blog and document some of what I have been doing recently. You can find the blog at [1] if you're interested. The first post goes over the work from the last month or so. Future posts should be shorter and on more specific topics. There's an overview of what has happened/changed/will change at the bottom of the post if you're short on time. Thanks. [1] - http://fuuzetsu.co.uk/blog -- Mateusz K. 0x2ADA9A97.asc Description: application/pgp-keys ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSOC project progress
Hi Mateusz, This looks great — I'm especially excited about List entries no longer have to be separated by empty lines! However, the decision to use Attoparsec (instead of Parsec, say) strikes me as a bit odd, as it wasn't intended for parsing source code. In particular, I'm concerned with error messages this parser would produce. Roman * Mateusz Kowalczyk fuuze...@fuuzetsu.co.uk [2013-07-30 23:35:45+0100] Greetings cafe, As some of you might know, I'm hacking on Haddock as part of Google Summer of Code. I was recently advised to create a blog and document some of what I have been doing recently. You can find the blog at [1] if you're interested. The first post goes over the work from the last month or so. Future posts should be shorter and on more specific topics. There's an overview of what has happened/changed/will change at the bottom of the post if you're short on time. Thanks. [1] - http://fuuzetsu.co.uk/blog ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Haddock GSoC project
I'm interested in being a GSoC student, and the Haddock-related tickets looked like a good place to start http://hackage.haskell.org/trac/summer-of-code/ticket/1567 http://hackage.haskell.org/trac/summer-of-code/ticket/1568 http://hackage.haskell.org/trac/summer-of-code/ticket/1569 ... haddock could use some love! And I love documentation. I think I'd start by hacking on some relatively easy Haddock tickets to find my way around the code and the hacking process. Then it might be time to move into one of the bigger projects (I'm tempted to say #1567, Haddock: allow documentation to propagate between packages), depending on priorities; probably still working on some smaller but important Haddock tickets. Then it depends how much time we have left in the summer, there's a lot that can be done! - I've hacked on the GHC lexing/parsing code a bit, and I know darcs, haskell, etc., and I've been around watching on mailing-lists since before Haddock 2.x, so I feel like I have a fair amount of context with which to approach this project. What do you think, is this a good project to look towards? What's the next step... should I elaborate my proposal by looking at Haddock tickets and their priorities? But I should have your feedback first; what do the mentors, or the Haskell community, want most to be improved about Haddock? -Isaac ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock GSoC project
Having cross-package links would be pure awesome. On Wed, Mar 25, 2009 at 10:04 AM, Isaac Dupree m...@isaac.cedarswampstudios.org wrote: I'm interested in being a GSoC student, and the Haddock-related tickets looked like a good place to start http://hackage.haskell.org/trac/summer-of-code/ticket/1567 http://hackage.haskell.org/trac/summer-of-code/ticket/1568 http://hackage.haskell.org/trac/summer-of-code/ticket/1569 ... haddock could use some love! And I love documentation. I think I'd start by hacking on some relatively easy Haddock tickets to find my way around the code and the hacking process. Then it might be time to move into one of the bigger projects (I'm tempted to say #1567, Haddock: allow documentation to propagate between packages), depending on priorities; probably still working on some smaller but important Haddock tickets. Then it depends how much time we have left in the summer, there's a lot that can be done! - I've hacked on the GHC lexing/parsing code a bit, and I know darcs, haskell, etc., and I've been around watching on mailing-lists since before Haddock 2.x, so I feel like I have a fair amount of context with which to approach this project. What do you think, is this a good project to look towards? What's the next step... should I elaborate my proposal by looking at Haddock tickets and their priorities? But I should have your feedback first; what do the mentors, or the Haskell community, want most to be improved about Haddock? -Isaac ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- /jve ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
