Re: [Haskell-cafe] Sparse documentation
Hi Andrew, On Wed, Jul 04, 2007 at 07:26:48PM +0100, Andrew Coppin wrote: Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It’s not hard to do (grab the Darcs repo, type away), and it’s widely appreciated. How exactly do I get started? (Obviously I can't write the documentation for the monad transformers - I don't know how they work yet! But I could have a go at splicing all the Parsec goodness into the Haddoc pages...) Get the latest source: darcs get http://darcs.haskell.org/packages/parsec cd parsec Build the Cabal Setup program and configure the package: ghc --make Setup ./Setup configure Then actually update the documentation, in Text/ParserCombinators/... Now run haddock: ./Setup haddock and check that it looks reasonable. Open dist/doc/html/index.html in your web browser and follow the relevant links. It's probably also a good idea to check you haven't broken the code by accident, i.e. test that it still builds: ./Setup build If you are happy then record and send the patch: darcs record darcs send If you think that the patch might be at all contentious then you should follow the library submissions procedure instead of the last step: http://www.haskell.org/haskellwiki/Library_submissions but for just adding brief haddock docs that's probably overkill. Thanks Ian ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
RE: [Haskell-cafe] Sparse documentation
| Fortunately, some kind soul has gone through and converted the | documentation to haddock format: | http://hackage.haskell.org/trac/ghc/ticket/1410 | | So it'll all appear in the html docs in the next version. In the mean | time one can look at the haddock comments in the source: | http://darcs.haskell.org/packages/mtl/Control/Monad/ Furthermore, you can always get the GHC HEAD documentation here http://www.haskell.org/ghc/dist/current/docs From there you can get to Control.Monad, which indeed shows at least some documentation. Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
RE: [Haskell-cafe] Sparse documentation
Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It's not hard to do (grab the Darcs repo, type away), and it's widely appreciated. People often don't feel qualified do to this, but documentation written by an intelligent but unqualified person (perhaps including not sure what happens here) is a lot more useful than no documentation at all. Yes I know that misleading documentation can be a Bad Thing but I think lack of documentation is a much bigger problem than misleading documentation, as of today. Simon From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Brent Yorgey Sent: 03 July 2007 22:09 To: Andrew Coppin Cc: haskell-cafe@haskell.org Subject: Re: [Haskell-cafe] Sparse documentation It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something... I certainly don't disagree with you! I was just commenting on the tendency of the community to document things in academic papers. But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries. After many hours tying my brain in knots, I *think* I need to use a monad transformer... but I've never ever done that before. So I'd like to learn how it works. Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html. I found that paper very clear and helpful in learning to use monad transformers. Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers. -Brent ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
RE: [Haskell-cafe] Sparse documentation
On Wed, 2007-04-07 at 08:03 +0100, Simon Peyton-Jones wrote: | Fortunately, some kind soul has gone through and converted the | documentation to haddock format: | http://hackage.haskell.org/trac/ghc/ticket/1410 | | So it'll all appear in the html docs in the next version. In the mean | time one can look at the haddock comments in the source: | http://darcs.haskell.org/packages/mtl/Control/Monad/ Furthermore, you can always get the GHC HEAD documentation here http://www.haskell.org/ghc/dist/current/docs From there you can get to Control.Monad, which indeed shows at least some documentation. Simon, if the less-talented among us (like me) want to contribute to GHC's docs -- and especially documenting the libraries -- what's the best way to go about this? I'm not too comfortable with the notion of just going into GHC's guts and Haddocking the comments, contributing patches willy-nilly because I'd not be certain I did the job right, that I explained things correctly where I had to amplify, etc. Is there some kind of documentation team we poor souls could interact with to assist? -- Michael T. Richter [EMAIL PROTECTED] (GoogleTalk: [EMAIL PROTECTED]) When debugging, novices insert corrective code; experts remove defective code. (Richard Pattis) signature.asc Description: This is a digitally signed message part ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Andrew Coppin wrote: Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it. I doubt monad transformers are the answer. I imagine you just want to one run parser over the result of the previous, which is just function composition, modulo a sensible way of handling errors. If you give more details on what you're trying, people may have helpful insights. Or not :) Jules ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Simon, if the less-talented among us (like me) want to contribute to GHC's docs -- and especially documenting the libraries -- what's the best way to go about this? I'm not too comfortable with the notion of just going into GHC's guts and Haddocking the comments, contributing patches willy-nilly because I'd not be certain I did the job right, that I explained things correctly where I had to amplify, etc. Is there some kind of documentation team we poor souls could interact with to assist? there was the idea of using the wiki for developing documentation improvements, prior to actually submitting the improved texts. the only hint of that scheme i can find right now is: http://www.haskell.org/haskellwiki/Improving_library_documentation but establishing a documentation team to help organise the process and to define a realistic workflow (how and where to edit, how and who submits when its ready, how to avoid extra work due to working in different formats, ..) seems like a good idea. go for it!-) claus ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Simon Peyton-Jones wrote: Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It’s not hard to do (grab the Darcs repo, type away), and it’s widely appreciated. People often don’t feel “qualified” do to this, but documentation written by an intelligent but “unqualified” person (perhaps including “not sure what happens here”) is a lot more useful than no documentation at all. Yes I know that misleading documentation can be a Bad Thing but I think lack of documentation is a much bigger problem than misleading documentation, as of today. Simon How exactly do I get started? (Obviously I can't write the documentation for the monad transformers - I don't know how they work yet! But I could have a go at splicing all the Parsec goodness into the Haddoc pages...) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Jules Bean wrote: Andrew Coppin wrote: Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it. I doubt monad transformers are the answer. I imagine you just want to one run parser over the result of the previous, which is just function composition, modulo a sensible way of handling errors. If you give more details on what you're trying, people may have helpful insights. Or not :) Yeah, running one parser on top of another isn't inherently hard. The *hard* thing is that I want to stack several parsers on top of each other, and *change* that stack at various points in the parsing. After many hours of trying, I did eventually get working code. But *damn* it's complicated! (Especially the type signatures.) Hopefully I'll find a way to simplify it gradually... As for asking here... I did, and nobody had anything interesting to say. :-( ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says Inspired by some paper (http://www.ogi.edu/csee/~mpj/) It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information. Is there a particular module you're having trouble with? Or just griping in general? =) -Brent ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Is there a particular module you're having trouble with? Or just griping in general? =) How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference? -Brent Tim Newsham http://www.thenewsh.com/~newsham/ ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
On Tue, 2007-07-03 at 15:11 -0400, Brent Yorgey wrote: Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says Inspired by some paper (http://www.ogi.edu/csee/~mpj/) It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information. Actually, the code was documented in comments in the code, just not in haddock format. :-( Fortunately, some kind soul has gone through and converted the documentation to haddock format: http://hackage.haskell.org/trac/ghc/ticket/1410 So it'll all appear in the html docs in the next version. In the mean time one can look at the haddock comments in the source: http://darcs.haskell.org/packages/mtl/Control/Monad/ Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
the references have not been updated, it seems. but once you've used the name Mark P Jones, mentioned next to the link, to google for a current url for his publications page, you'll (a) find a treasure-trove of haskell papers http://web.cecs.pdx.edu/~mpj/ (b) be able to submit a fix for the documentation bug to the library maintainer, which 'ghc-pkg describe mtl' lists as [EMAIL PROTECTED] (c) indicate to the maintainer what additional information you would find helpful in the haddocks, and perhaps help to get it there (several libraries have acquired more directly useful haddocks this way, including parts of the monad libs, with the permission of paper and tutorial authors, but there are still quite a few gaps waiting to be filled) (did i mention that putting bug reports in parentheses in emails is not the best way to attract attention, get the bug recorded, or fixed?-) claus - Original Message - From: Andrew Coppin [EMAIL PROTECTED] To: haskell-cafe@haskell.org Sent: Tuesday, July 03, 2007 7:38 PM Subject: [Haskell-cafe] Sparse documentation Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says Inspired by some paper (http://www.ogi.edu/csee/~mpj/) and then just shows you a bunch of type signatures, without telling you *anything* about what the module is supposed to be for, or what all these classes, types, methods and functions are meant to *do*? I'm currently struggling with a really knotty problem, and the last thing I need is unhelpful documentation. :-S (Did I mention that that URL goes nowhere?) ___ 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] Sparse documentation
On Tue, 3 Jul 2007 09:23:02 -1000 (HST) Tim Newsham [EMAIL PROTECTED] wrote: How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference? -Brent Tim Newsham http://www.thenewsh.com/~newsham/ What is missing in STM's documentation? TArray, TChan, TMVar have just as much documentation as their non-transactional counterparts. The documentation for TVar and STM is also available, but perhaps more difficult to find. Note that Control.Concurrent.STM.TVar (similarly Control.Monad.STM) does not have any documentation on the page, but each identifier is a link to GHC specific modules that give more documentation. This is a bug in Haddock: it doesn't know how to include documentation from another package. Cheers, Spencer Janssen Documentation: http://www.haskell.org/ghc/docs/latest/html/libraries/stm/Control-Concurrent-STM-TVar.html http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC-Conc.html#t%3ATVar http://www.haskell.org/ghc/docs/latest/html/libraries/stm/Control-Monad-STM.html http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC-Conc.html#t%3ASTM etc. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Tim Newsham wrote: Is there a particular module you're having trouble with? Or just griping in general? =) How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference? Similar remarks hold for Parsec. The online manual is very well done, and I learned the thing easily and painlessly. But the online documentation is one 1,000 mile long HTML page. On the other hand, the nicely browsable API docs contain virtually nothing except the type signatures... On the one hand, in Haskell (unlike any other language I've ever seen) you can often *almost* tell what something does just form the type. (Pretty amazing, really.) OTOH, sometimes you can't... ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
Brent Yorgey wrote: Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says Inspired by some paper (http://www.ogi.edu/csee/~mpj/ http://www.ogi.edu/csee/%7Empj/) It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information. It's probably damn useful to have the paper *as well*. You know, for some context, a nice overview, introductory material, etc. (I mean, if the link worked...) It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something... Is there a particular module you're having trouble with? Or just griping in general? =) After many hours tying my brain in knots, I *think* I need to use a monad transformer... but I've never ever done that before. So I'd like to learn how it works. (And then I'd like to figure out what standard monads are out there and what they do.) But the docs aren't helping me greatly in this regard. (I notice the Wiki is also somewhat devoid of any material on this subject...) Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something... I certainly don't disagree with you! I was just commenting on the tendency of the community to document things in academic papers. But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries. After many hours tying my brain in knots, I *think* I need to use a monad transformer... but I've never ever done that before. So I'd like to learn how it works. Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html. I found that paper very clear and helpful in learning to use monad transformers. Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers. -Brent ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Sparse documentation
It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something... agreed. for me, the perldocs for most of the well-used perl packages are the gold standard. do a perldoc on the LWP or DBI modules, for example. i often find myself using a combination of the api docs and the zvon reference. examples are essential. it would be nice to merge these two documentation sources. from http://zvon.org/index.php?nav_id=legalmime=html i see that zvon employs a form of bsd (attribution) license of course if i can help improve documentation, let me know. its one thing that novice/hobbyist haskellers can contribute effectively ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
