Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
The problem isn't social pressure to be stable, it's the ambiguity of what stable means. If Hackage 2 institutes a policy whereby things claiming to be stable are treated better, then stable is likely to become the new experimental. I'd say, rather than rely on social agreement on what terms mean, let's just collect lots of automated metrics, and present them as extra information on the hackage pages. At work, we have all modules scored by hlint metrics, and doclint metrics. (Doclint complains about modules without a module header comment, and type signatures without haddock comments.) We count infractions and have a top ten hall-of-shame, as well as placing the scores in the module documentation itself. We also have a fingerprint for every release (basically the API type signatures), and the size of fingerprint-diffs between releases is a rough measure of API-churn. Some of these measures are designed to place social pressure on authors to improve their code/documentation, but they have a dual role in allowing users to get a feel for the quality of the code they are using, without imposing any external hierarchy on which metrics are more important in any given situation. Regards, Malcolm ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On 10/25/11 3:54 AM, Gregory Collins wrote: On Tue, Oct 25, 2011 at 4:34 AM, wren ng thorntonw...@freegeek.org wrote: I'm not so sure about that exemption. The experimental stability level seems to be the norm on Hackage and often means I use this for real projects, but because I use it for real projects I'm not quite willing to hammer the API in stone just yet. ... Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP. I think there's no need to cajole people into it -- if Hackage 2 puts stable packages on a different / better list, there's your social pressure. Right now the stability flag in the .cabal file, as you pointed out, is almost completely content-free. The problem isn't social pressure to be stable, it's the ambiguity of what stable means. If Hackage 2 institutes a policy whereby things claiming to be stable are treated better, then stable is likely to become the new experimental. Just because I call something stable doesn't mean that it is. Just because I give something enough documentation so appease the bots so that I'm allowed to call it stable doesn't mean that it is. Frankly, giving a one-line synopsis of what a function does isn't a high enough barrier to entry to keep someone from abusing the system in order to self-select which index page they get put on. The only way to get a consensus about what stable, experimental, etc mean is ...to get a consensus about what they mean. It's exactly the same thing as the PVP: in order to get people to agree about what version increments mean, we need to get them to agree to mean whatever it is everybody else thinks they mean. Automating the verification of that agreement is a nice tool to have to hand, but it's meaningless without the agreement about what we're all engaged in. -- Live well, ~wren ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Tue, Oct 25, 2011 at 4:34 AM, wren ng thornton w...@freegeek.org wrote: I'm not so sure about that exemption. The experimental stability level seems to be the norm on Hackage and often means I use this for real projects, but because I use it for real projects I'm not quite willing to hammer the API in stone just yet. ... Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP. I think there's no need to cajole people into it -- if Hackage 2 puts stable packages on a different / better list, there's your social pressure. Right now the stability flag in the .cabal file, as you pointed out, is almost completely content-free. G -- Gregory Collins g...@gregorycollins.net ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On 25 October 2011 18:54, Gregory Collins g...@gregorycollins.net wrote: On Tue, Oct 25, 2011 at 4:34 AM, wren ng thornton w...@freegeek.org wrote: I'm not so sure about that exemption. The experimental stability level seems to be the norm on Hackage and often means I use this for real projects, but because I use it for real projects I'm not quite willing to hammer the API in stone just yet. ... Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP. I think there's no need to cajole people into it -- if Hackage 2 puts stable packages on a different / better list, there's your social pressure. Right now the stability flag in the .cabal file, as you pointed out, is almost completely content-free. Right, but first we need to define what all those terms _mean_... and it's no good saying your package is stable if you change the API in a large-scale fashion every release. Also, by promoting packages that are self-picked as stable, this could stop people from picking a better package just because the maintainer is honest enough to state that they're still working on it... I mean, if base and containers keep changing, what can we _really_ say is a stable package? -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
Ivan Lazar Miljenovic ivan.miljeno...@gmail.com writes: Right, but first we need to define what all those terms _mean_... and it's no good saying your package is stable if you change the API in a large-scale fashion every release. I think there are better criteria to use, like: - do exported definition have Haddock comments? - does the package have an automated test suite? - is the package used by other packages? - ...by different authors? - has the package been recently updated? I'm sure there are other things as well that could be added. If this could be automatically checked, and displayed alongside the package name on Hackage (perhaps as adding one star per checklist item), it would encourage authors to actually improve their packages, rather than just label them stable. -k -- If I haven't seen further, it is by standing in the footprints of giants ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Tue, Oct 25, 2011 at 11:17, Ketil Malde ke...@malde.org wrote: Ivan Lazar Miljenovic ivan.miljeno...@gmail.com writes: Right, but first we need to define what all those terms _mean_... and it's no good saying your package is stable if you change the API in a large-scale fashion every release. I think there are better criteria to use, like: - do exported definition have Haddock comments? - does the package have an automated test suite? - is the package used by other packages? - ...by different authors? - has the package been recently updated? This is useful information, but to call it stability is not only misleading, but it also prevents the package from using that field to indicate whether or not it is stable! --Max ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On 25 October 2011 20:17, Ketil Malde ke...@malde.org wrote: Ivan Lazar Miljenovic ivan.miljeno...@gmail.com writes: Right, but first we need to define what all those terms _mean_... and it's no good saying your package is stable if you change the API in a large-scale fashion every release. I think there are better criteria to use, like: - do exported definition have Haddock comments? - does the package have an automated test suite? What about a test suite that either isn't packaged with the .cabal file or doesn't use Cabal's new test-suite architecture? Does the fact that it _has_ a test suite tell you it's rigorous? -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Tue, Oct 25, 2011 at 2:17 AM, Ketil Malde ke...@malde.org wrote: Ivan Lazar Miljenovic ivan.miljeno...@gmail.com writes: Right, but first we need to define what all those terms _mean_... and it's no good saying your package is stable if you change the API in a large-scale fashion every release. I think there are better criteria to use, like: - do exported definition have Haddock comments? - does the package have an automated test suite? - is the package used by other packages? - ...by different authors? These signals might not apply if the package is primarily a binary. - has the package been recently updated? This one is also tricky. A stable package is a good thing! On the other hand, a package that is broken by a new version of ghc and then takes months to be updated is not so great. What matters is maintainer responsiveness and that's not so easily measurable. I feel like use-derived signals are safer. E.g. number of downloads, user ratings, user reviews, depending packages. But that stuff obviously goes in a separate section, not a .cabal field. With ratings or reviews it's tricky because you want to make sure they apply to specific versions, so obsolete complaints about a fixed bug don't hang around forever. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
Max Rabkin max.rab...@gmail.com writes: This is useful information, but to call it stability is not only misleading, but it also prevents the package from using that field to indicate whether or not it is stable! Oh, right - I'm not much interested in the stability of a package. What I want to know, is which package to choose for some purpose. By highlighting stuff that is correlated with usefulness, I'll be able to make a quicker, more informed decision. Separating this from stability is a feature, not a bug, since it frees the author to label the package stable or not - instead of encouraging using stable to mean please use. :-) -k -- If I haven't seen further, it is by standing in the footprints of giants ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Mon, Oct 10, 2011 at 09:06:01AM +0100, Paterson, Ross wrote: The distinction between synopsis and description is borrowed from the Debian package format: http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions The two fields are aimed at different audiences. Not in Debian. The synopsis and description are a bit like the title and the abstract of a scholarly paper: you might see a title without the abstract (and it must work alone), but both are aimed at the same audience - people who are unsure whether they should read the paper (install the package) and look for information sufficient to decide that it's not what they need (or that it probably is). -- Antti-Juhani Kaijanaho, Jyväskylä, Finland http://antti-juhani.kaijanaho.fi/newblog/ http://www.flickr.com/photos/antti-juhani/ ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
Good point. On the other hand, nobody points package authors to the Debian documentation (and Debian also has review for newly uploaded packages, as far as I know). Re: review process -- Perhaps there would be a use for a review process somewhere between haskell-platform and the unwashed masses? HP covers a very small percentage of packages, but a larger percentage could probably pass some kind of review akin to the debian process. And it would be a good forcing function to get people to do the things they don't get around to -Ryan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Mon, Oct 24, 2011 at 12:55 PM, Ryan Newton rrnew...@gmail.com wrote: Good point. On the other hand, nobody points package authors to the Debian documentation (and Debian also has review for newly uploaded packages, as far as I know). Re: review process -- Perhaps there would be a use for a review process somewhere between haskell-platform and the unwashed masses? HP covers a very small percentage of packages, but a larger percentage could probably pass some kind of review akin to the debian process. And it would be a good forcing function to get people to do the things they don't get around to I'm skeptical. We seem to have trouble getting enough of people's spare time to tackle interesting engineer work, let alone relatively thankless administrative/bureaucratic/procedural work. If people are going to devote time towards solving this particular problem (poorly documented libraries), an interesting first step would be to try solving the problem using technological means, i.e.: prohibit or otherwise discourage uploads to hackage that fail automatically-verifiable criteria here. Examples could include: Your package lacks a description, more than X% of your modules lack toplevel module comments, fewer than Y% of your toplevel exports have haddock comments, etc... Packages with stability=experimental would probably be exempt from the requirements. Duncan could probably comment authoritatively, but I'm guessing Hackage 2 might provide a better framework for tackling these kinds of policy issues, because it would probably allow you to e.g. filter the package list by stability. G -- Gregory Collins g...@gregorycollins.net ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On 10/24/11 12:34 PM, Gregory Collins wrote: Examples could include: Your package lacks a description, more than X% of your modules lack toplevel module comments, fewer than Y% of your toplevel exports have haddock comments, etc... Packages with stability=experimental would probably be exempt from the requirements. I'm not so sure about that exemption. The experimental stability level seems to be the norm on Hackage and often means I use this for real projects, but because I use it for real projects I'm not quite willing to hammer the API in stone just yet. Surely we should distinguish this level of stability from no seriously I'm just goofing around with category theory, but unfortunately both classes of project are called experimental. While the latter may deserve a pass (to encourage goofing around with category theory :), the lack of documentation for the former seems to me like the main motivation for instituting such an automatic system in the first place. Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP. -- Live well, ~wren ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On 25 October 2011 13:34, wren ng thornton w...@freegeek.org wrote: Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP. +1, not to mention all the to-level fields available in Haddock (portable, etc.) as well. -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Mon, Oct 10, 2011 at 03:17, John Millikin jmilli...@gmail.com wrote:
The package summary is Type-safe ADT-database mapping library., which
gives some idea about what it does.
Whence my suggestion to show this on the package's page. Perhaps I
shouldn't have hidden that at the bottom -- I meant this as my main
point, and I'm afraid I got a little side-tracked.
In my experience, any package that starts its source files with
{-# LANGUAGE GADTs, TypeFamilies, ExistentialQuantification,
StandaloneDeriving, TypeSynonymInstances, MultiParamTypeClasses,
FunctionalDependencies, FlexibleInstances, FlexibleContexts,
OverlappingInstances, ScopedTypeVariables, GeneralizedNewtypeDeriving,
UndecidableInstances, EmptyDataDecls #-}
is probably an experiment in what is possible, rather than a
production-friendly library.
An experiment that I was interested in, and hoped to find out more
about. But anyway, I see your point.
Many people upload experimental packages to Hackage so that they can be used
by other interested people, even though the packages are not ready/intended
for mass consumption. A lack of documentation in such cases is
understandable.
Some way of documenting this fact would, however, be helpful.
I wonder if it would be worth giving package uploaders control over whether
their packages are shown on the package list? Packages can be manually
hidden by emailing an admin, but that's a lot of trouble.
In this case I followed an external link, so that would not have
helped me. There is the stability field, which has an experimental
value, but it's not at all clear what the different values mean other
than stable.
It is fair that some packages on Hackage are not intended for human
consumption. Perhaps this is caused in part by having our package
installer and humans looking in the same place for information about
Haskell libraries. But I think we can do a better job of
distinguishing these packages. Perhaps a visibility or
release-status field?
--Max
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
Max Rabkin writes: But I also have a concrete suggestion for Hackage: include the package synopsis on the package's page. The distinction between synopsis and description can be confusing, and sometimes it seems to violate DRY to have the same info in both. You may have missed the header on the package page (dark line at the top). The distinction between synopsis and description is borrowed from the Debian package format: http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions The two fields are aimed at different audiences. A Synopsis trying to do double duty as the beginning of a general package description won't work as well as a stand-alone summary for package lists, etc. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
On Mon, Oct 10, 2011 at 10:06, Paterson, Ross r.pater...@city.ac.uk wrote: Max Rabkin writes: But I also have a concrete suggestion for Hackage: include the package synopsis on the package's page. The distinction between synopsis and description can be confusing, and sometimes it seems to violate DRY to have the same info in both. You may have missed the header on the package page (dark line at the top). I did indeed. Perhaps it should be bigger? I've just opened up Synaptic, and it is indeed separate from the description, but there the synopsis is used as a heading for the description, and it's the biggest thing on the screen (whereas Hackage uses package name). The distinction between synopsis and description is borrowed from the Debian package format: http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions The two fields are aimed at different audiences. A Synopsis trying to do double duty as the beginning of a general package description won't work as well as a stand-alone summary for package lists, etc. Good point. On the other hand, nobody points package authors to the Debian documentation (and Debian also has review for newly uploaded packages, as far as I know). --Max ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package documentation complaints -- and a suggestion
The package summary is Type-safe ADT-database mapping library., which
gives some idea about what it does.
In my experience, any package that starts its source files with
{-# LANGUAGE GADTs, TypeFamilies, ExistentialQuantification,
StandaloneDeriving, TypeSynonymInstances, MultiParamTypeClasses,
FunctionalDependencies, FlexibleInstances, FlexibleContexts,
OverlappingInstances, ScopedTypeVariables, GeneralizedNewtypeDeriving,
UndecidableInstances, EmptyDataDecls #-}
is probably an experiment in what is possible, rather than a
production-friendly library.
Many people upload experimental packages to Hackage so that they can be used
by other interested people, even though the packages are not ready/intended
for mass consumption. A lack of documentation in such cases is
understandable.
I wonder if it would be worth giving package uploaders control over whether
their packages are shown on the package list? Packages can be manually
hidden by emailing an admin, but that's a lot of trouble.
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] YesodAuth documentation
I am surprised out of the whole list no one has stormed down on Nikita for wanting to store passwords as plain text. Nikita: never store passwords in plain text. Ever. D. On Mon, Jun 13, 2011 at 09:34, Никита Тимофеев ndtimof...@gmail.com wrote: Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? -- Timofeev N.D. ___ 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] YesodAuth documentation
When I review the original post I see only a question: Does passwords stored in a database in an unencrypted form? rather than a request. So I'm not sure that was the intent. I'm amazed that anyone (Sony!!!?) would store unencrypted passwords of course. Kevin On Jun 14, 10:21 am, cheater cheater cheate...@gmail.com wrote: I am surprised out of the whole list no one has stormed down on Nikita for wanting to store passwords as plain text. Nikita: never store passwords in plain text. Ever. D. On Mon, Jun 13, 2011 at 09:34, Никита Тимофеев ndtimof...@gmail.com wrote: Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? -- Timofeev N.D. ___ Haskell-Cafe mailing list haskell-c...@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-C...@haskell.orghttp://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] YesodAuth documentation
2011/6/14 Michael Steele mikesteel...@gmail.com: Actually, that's not entirely accurate. The Yesod scaffolding tool generates a site that uses mime-mail and sendmail, but there's nothing inherent in yesod-auth requiring either. My apologies for adding to the confusion. I see now that Yesod.Auth.Email handles database interactions, generates verify URLs for new accounts to use, and provides forms to embed in HTML. It doesn't actually create email messages or handle any kind of email delivery. I saw the mime-mail dependency, and then forgot where I had seen Network.Mail.Mime.renderSendMail actually being called. The stock email plugin does not let you disable these features, but it should be easy to write your own. You could just copy the email module from yesod-auth and make the modifications there. Or even better if you're so inclined: submit a patch to make these features optional. If you are so inclined, feel free to contact me for some guidance. My understanding is that none of the plugins included in yesod-auth are magic in any way. New ones can be created outside of the official package as long as their associated AuthPlugin has a Text value unique among any others being used. Is this all correct? Yes, that's completely accurate. Michael ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] YesodAuth documentation
Ah, I see how you could interpret what he wrote the way you describe. If that's what Nikita has meant, then that's all fine. Hope there's no harm in reminding this basic truth - better be safe than sorry! :) D. On Tue, Jun 14, 2011 at 15:00, Kevin Jardine kevinjard...@gmail.com wrote: When I review the original post I see only a question: Does passwords stored in a database in an unencrypted form? rather than a request. So I'm not sure that was the intent. I'm amazed that anyone (Sony!!!?) would store unencrypted passwords of course. Kevin On Jun 14, 10:21 am, cheater cheater cheate...@gmail.com wrote: I am surprised out of the whole list no one has stormed down on Nikita for wanting to store passwords as plain text. Nikita: never store passwords in plain text. Ever. D. On Mon, Jun 13, 2011 at 09:34, Никита Тимофеев ndtimof...@gmail.com wrote: Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? -- Timofeev N.D. ___ Haskell-Cafe mailing list haskell-c...@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-C...@haskell.orghttp://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] YesodAuth documentation
Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? Another example is Orangeroster [1]. For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? No. Email handling is done through the mime-mail package, which uses sendmail to do it's work. Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? The stock email plugin does not let you disable these features, but it should be easy to write your own. [1] : http://github.com/snoyberg/orangeroster 2011/6/13 Тимофеев Никита Дмитриевич ndtimof...@gmail.com Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? -- Timofeev N.D. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- -- Michael Steele ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] YesodAuth documentation
2011/6/13 Michael Steele mikesteel...@gmail.com: Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? Another example is Orangeroster [1]. For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? No. Email handling is done through the mime-mail package, which uses sendmail to do it's work. Actually, that's not entirely accurate. The Yesod scaffolding tool generates a site that uses mime-mail and sendmail, but there's nothing inherent in yesod-auth requiring either. Additionally, mime-mail includes a function to use the sendmail executable, but it can also be used with other packages, such as Haskellnet. I think we should move in the direction of making these integrations better. In fact, next time I need to set up a project that sends email, I'll likely be doing just that. Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? The stock email plugin does not let you disable these features, but it should be easy to write your own. You could just copy the email module from yesod-auth and make the modifications there. Or even better if you're so inclined: submit a patch to make these features optional. If you are so inclined, feel free to contact me for some guidance. Michael [1] : http://github.com/snoyberg/orangeroster 2011/6/13 Тимофеев Никита Дмитриевич ndtimof...@gmail.com Does exist some simple examples using yesod authentication except code of Haskellers site? Does exist some examples using YesodAuthEmail? For example, can i use third-party mail server instead of Sendmail for YesodAuthEmail? Can i disable registration confirmation? Does passwords stored in a database in an unencrypted form? -- Timofeev N.D. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- -- Michael Steele ___ 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] YesodAuth documentation
Actually, that's not entirely accurate. The Yesod scaffolding tool generates a site that uses mime-mail and sendmail, but there's nothing inherent in yesod-auth requiring either. My apologies for adding to the confusion. I see now that Yesod.Auth.Email handles database interactions, generates verify URLs for new accounts to use, and provides forms to embed in HTML. It doesn't actually create email messages or handle any kind of email delivery. I saw the mime-mail dependency, and then forgot where I had seen Network.Mail.Mime.renderSendMail actually being called. The stock email plugin does not let you disable these features, but it should be easy to write your own. You could just copy the email module from yesod-auth and make the modifications there. Or even better if you're so inclined: submit a patch to make these features optional. If you are so inclined, feel free to contact me for some guidance. My understanding is that none of the plugins included in yesod-auth are magic in any way. New ones can be created outside of the official package as long as their associated AuthPlugin has a Text value unique among any others being used. Is this all correct? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock: Documentation of instances with un-documentable type arguments
Hi Is there a similar ticket for GHC to not export instances in the case that other instances are explicitly specified? module Foo ( Foo(Monad) ) instance Monad Foo where ... instance MonadState (Foo Bar) where ... i.e. the monad instance gets exported but the MonadState one does not? This helps in maintaining opacity with respect to the package user. I may not want the user to be able to call 'get' and 'put' when using my custom monad. Cheers, Vivian On 26 August 2010 02:20, David Waern david.wa...@gmail.com wrote: 2010/8/25 Alexander McPhail haskell.vivian.mcph...@gmail.com: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? Yes, it should. BTW, we have a trac ticket for it: http://trac.haskell.org/haddock/ticket/37 You can add yourself to the CC list to show that you want this feature. Currently we don't have many people working on these types of tickets in Haddock (I'm mostly fixing bugs, others are working on bigger improvements), so if more people would volunteer to help out, that'd be great. The mailing list hadd...@projects.haskell.org can be used to ask for directions and help. David -- --- yolar et elver. --- DISCLAIMER This transmission contains information that may be confidential. It is intended for the named addressee only. Unless you are the named addressee you may not copy or use it or disclose it to anyone else. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock: Documentation of instances with un-documentable type arguments
On 4 September 2010 19:01, Alexander McPhail haskell.vivian.mcph...@gmail.com wrote: Hi Is there a similar ticket for GHC to not export instances in the case that other instances are explicitly specified? module Foo ( Foo(Monad) ) instance Monad Foo where ... instance MonadState (Foo Bar) where ... i.e. the monad instance gets exported but the MonadState one does not? This helps in maintaining opacity with respect to the package user. I may not want the user to be able to call 'get' and 'put' when using my custom monad. No: instances are implicitly imported and exported (if the class and the type are visible, then so are any possible instances). -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
Don Stewart wrote: andrewcoppin: Almost every release of GHC that I can remember has had the links for the mtl package broken. (The Control.Monad.XXX modules are mostly from mtl. But, for example, Control.Monad.Fix is from base. I bet you'll find it works just fine.) Well spotted, Andrew! The way to get things like this fixed is to report a bug to the relevant project. M'kay. And for this, that would be...? Click on the 'bug report' button: http://trac.haskell.org/haskell-platform/ Ah, right. There's a HP-specific tracker. I guess now I just have to go register my details with yet *another* tracker and then I can report it. (Right after I finish checking that nobody has already reported it for me...) You installed the Haskell Platform on Windows, so please mention this in the bug ticket. The problem will likely be in the Windows installer script, and what docs were bundled with that specific installer. Be as detailed in the report as you can, to make sure we can reproduce what trouble you have. The information above probably says it all, so that shouldn't be hard. In the meantime, you can always read the 'mtl' documentation on its package page: http://hackage.haskell.org/package/mtl Well, yeah, there is that. It's just annoying to click on certain links and find it's dead, even if there is a workaround. (Assuming you have Internet access, which you occasionally don't...) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
Arnaud Bailly wrote: Hello, I installed (succesfully) HAskell Platform 2010.2 on windows and have a small but annoying issue: Some links in HTML documentation lead to broken links. I did not investigate all the links, but I have seen that all doc under Control.Monad.XXX is missing. What am I doing wrong ? Almost every release of GHC that I can remember has had the links for the mtl package broken. (The Control.Monad.XXX modules are mostly from mtl. But, for example, Control.Monad.Fix is from base. I bet you'll find it works just fine.) Today I went and did a thorough check. HP 2009.2.x.x (I forget exactly which one) has links that point to C:\Program Files\Haskell Platform\2009.2.x.x\doc\ghc-mtl-x.x.x which does not exist. There is, however, a folder named C:\Program Files\Haskell Platform\2009.2.x.x\doc\mtl-x.x.x which exists just fine, and appears to contain the correct stuff. In HP 2010.1.0.0 and 2010.2.0.0, the links point to the latter address, but no such folder actually exists. The mtl documentation appears to simply be missing entirely, rather than being in a different place than where the links point to. Various older releases of GHC (before HP existed) have had one problem or the other, always with mtl, never with any other package. I have absolutely no idea why mtl is always broken, but all the other packages seem to work just fine. The fact that it happens so routinely suggests a problem with the build process rather than a one-off mistake. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
andrewcoppin: Arnaud Bailly wrote: Hello, I installed (succesfully) HAskell Platform 2010.2 on windows and have a small but annoying issue: Some links in HTML documentation lead to broken links. I did not investigate all the links, but I have seen that all doc under Control.Monad.XXX is missing. What am I doing wrong ? Almost every release of GHC that I can remember has had the links for the mtl package broken. (The Control.Monad.XXX modules are mostly from mtl. But, for example, Control.Monad.Fix is from base. I bet you'll find it works just fine.) Well spotted, Andrew! The way to get things like this fixed is to report a bug to the relevant project. Click on the 'bug report' button: http://trac.haskell.org/haskell-platform/ You installed the Haskell Platform on Windows, so please mention this in the bug ticket. The problem will likely be in the Windows installer script, and what docs were bundled with that specific installer. Be as detailed in the report as you can, to make sure we can reproduce what trouble you have. In the meantime, you can always read the 'mtl' documentation on its package page: http://hackage.haskell.org/package/mtl -- Don ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
On Thursday 02 September 2010 19:34:07, Don Stewart wrote: andrewcoppin: Arnaud Bailly wrote: Hello, I installed (succesfully) HAskell Platform 2010.2 on windows and have a small but annoying issue: Some links in HTML documentation lead to broken links. I did not investigate all the links, but I have seen that all doc under Control.Monad.XXX is missing. What am I doing wrong ? Almost every release of GHC that I can remember has had the links for the mtl package broken. (The Control.Monad.XXX modules are mostly from mtl. But, for example, Control.Monad.Fix is from base. I bet you'll find it works just fine.) Well spotted, Andrew! The way to get things like this fixed is to report a bug to the relevant project. Click on the 'bug report' button: http://trac.haskell.org/haskell-platform/ You installed the Haskell Platform on Windows, so please mention this in the bug ticket. The problem will likely be in the Windows installer script, and what docs were bundled with that specific installer. Probably not. I'm on Linux and build my GHCs from source. There's no directory mtl-1.1.0.2 in ~/share/doc/ghc/html/libraries although it's linked to from the package index built with the compiler. (Hadn't noticed before because I use the index in ~/.cabal). Seems to be a slip-up in the makefiles. Be as detailed in the report as you can, to make sure we can reproduce what trouble you have. In the meantime, you can always read the 'mtl' documentation on its package page: http://hackage.haskell.org/package/mtl -- Don ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
On Thursday 02 September 2010 20:05:12, Daniel Fischer wrote: Probably not. I'm on Linux and build my GHCs from source. There's no directory mtl-1.1.0.2 in ~/share/doc/ghc/html/libraries although it's linked to from the package index built with the compiler. (Hadn't noticed before because I use the index in ~/.cabal). Seems to be a slip-up in the makefiles. Also broken: utf8-string haskeline terminfo ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
On Thu, Sep 2, 2010 at 8:20 PM, Daniel Fischer daniel.is.fisc...@web.de wrote: On Thursday 02 September 2010 20:05:12, Daniel Fischer wrote: Probably not. I'm on Linux and build my GHCs from source. There's no directory mtl-1.1.0.2 in ~/share/doc/ghc/html/libraries although it's linked to from the package index built with the compiler. (Hadn't noticed before because I use the index in ~/.cabal). Seems to be a slip-up in the makefiles. Also broken: utf8-string haskeline terminfo Note that on Hackage all links in haddock pages to the current base library (4.2.0.2) are broken. Possibly because the documentation for base-4.2.0.2 was not build. The docs for base-4.2.0.1 are build fine: http://hackage.haskell.org/package/base Regards, Bas ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation in Haskell Platform on Windows
On 1 September 2010 14:25, Arnaud Bailly arnaud.oq...@gmail.com wrote: Hello, I installed (succesfully) HAskell Platform 2010.2 on windows and have a small but annoying issue: Some links in HTML documentation lead to broken links. I did not investigate all the links, but I have seen that all doc under Control.Monad.XXX is missing. What am I doing wrong ? Is this in the documentation for GHC? Sometimes Haddock links to libraries used when building GHC but aren't shipped with GHC; I'm not sure how to deal with this. (Note: this isn't a Windows-specific problem; it also occurs on Gentoo Linux for example.) Arnaud ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock: Documentation of instances with un-documentable type arguments
2010/8/25 Alexander McPhail haskell.vivian.mcph...@gmail.com: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? Yes, it should. BTW, we have a trac ticket for it: http://trac.haskell.org/haddock/ticket/37 You can add yourself to the CC list to show that you want this feature. Currently we don't have many people working on these types of tickets in Haddock (I'm mostly fixing bugs, others are working on bigger improvements), so if more people would volunteer to help out, that'd be great. The mailing list hadd...@projects.haskell.org can be used to ask for directions and help. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
2010/7/23 Ivan Miljenovic ivan.miljeno...@gmail.com: On 22 July 2010 18:33, David Waern david.wa...@gmail.com wrote: [snip] We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. Would you have some kind of inbuilt time limit (similar to what mueval has) for very long/complex QC tests? I have some that take quite a while to run... The testing is carried out by a separate program: DocTest. There is no support for QC properties yet. Some kind of time limit would probably be useful to have, yes. Thanks for the suggestion. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
2010/7/21 Richard O'Keefe o...@cs.otago.ac.nz: One of the really nice ideas in the R statistics system is that documentation pages can contain executable examples, and when you wrap up a package for distribution, the system checks that the examples run as advertised. The next version of Haddock will support something like this, implemented by SImon Hengel. Here's an example of how to use the new markup: -- | An example: -- -- ghci fib 10 -- 55 -- Haskell has a *perfect* fit for this idea in QuickCheck. We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
David Waern wrote: 2010/7/21 Richard O'Keefe o...@cs.otago.ac.nz: One of the really nice ideas in the R statistics system is that documentation pages can contain executable examples, and when you wrap up a package for distribution, the system checks that the examples run as advertised. The next version of Haddock will support something like this, implemented by SImon Hengel. Here's an example of how to use the new markup: -- | An example: -- -- ghci fib 10 -- 55 Awesome. This is similar to Python's thing. Haskell has a *perfect* fit for this idea in QuickCheck. We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. Also support SmallCheck/LazySmallCheck, pretty please? :) -- Live well, ~wren ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
Alexander Solla wrote: After all, the source is always structured in more-or-less the same way. Fragments of text with opaque -- unless/until you understand them -- combinators join two distinct concepts/types into functions. A chain of functions (potentially at various levels of abstraction) is a computation. You use these things by finding a chain of types (Start - A), (A - B), (B - C), ... (N - Goal) and composing, filling in additional details as necessary. Building that chain means doing depth first searches on a tree/graph of possibilities, and usually isn't so much fun. The library developer is in the best position to do exactly that, having already done it while constructing the library. In Haskell even learning to use a library has an algebraic structure. ;^) Actually, I was thinking just this afternoon... If you're writing in an OO language, you can use UML to produce diagrams that give you a kind of at-a-glance overview of the saliant parts of something. (Depending on how much detail you choose to include in the diagram.) I wander if anybody has a standardised notation that might be applicable to FP in general or Haskell specifically... ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
On 22 July 2010 18:33, David Waern david.wa...@gmail.com wrote: [snip] We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. Would you have some kind of inbuilt time limit (similar to what mueval has) for very long/complex QC tests? I have some that take quite a while to run... David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
Ivan Miljenovic wrote: * When writing the code, it's obvious what it does; as such you may think any documentation you may offer is trivial (down the track, however...). * The author is familiar with a library; as such it may not be obvious what extra documentation could be needed. This is the inherant problem with any kind of documentation. (And it's by no means limited to Haskell...) The person most qualified to explain stuff is the one least qualified to know what needs explaining! ;-) I would also like to draw attention to something else: Haddock offers solid support for writing the this function does X, that function does Y type of documentation. It has really very weak support for writing general overviews, tutorials, examples, etc. Yes, you can put example code into the documentation for a specific module. But look at, say, the Parsec documentation at http://legacy.cs.uu.nl/daan/download/parsec/parsec.html This tells a new user *far* more than any API listing. And yet, Haddock doesn't really support writing this kind of thing properly... ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
On Jul 20, 2010, at 10:28 PM, Richard O'Keefe wrote: What I don't see is HOW DO I USE THIS STUFF? I think tutorials are the best way to do that (i.e., example normal forms for the computations the library intends to expose). Perl's package archive (the cpan) traditionally uses a Synopsis section that exposes representative functions at each layer/step: http://search.cpan.org/~lds/GD-2.45/GD.pm for example. After all, the source is always structured in more-or-less the same way. Fragments of text with opaque -- unless/until you understand them -- combinators join two distinct concepts/types into functions. A chain of functions (potentially at various levels of abstraction) is a computation. You use these things by finding a chain of types (Start - A), (A - B), (B - C), ... (N - Goal) and composing, filling in additional details as necessary. Building that chain means doing depth first searches on a tree/graph of possibilities, and usually isn't so much fun. The library developer is in the best position to do exactly that, having already done it while constructing the library.___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
On 21 July 2010 15:28, Richard O'Keefe o...@cs.otago.ac.nz wrote: I'm giving some lectures this week about how to _read_ programs, and I've had some things to say about JavaDoc and wondered whether to show some examples of Haddock. I took a certain library that has been mentioned recently in this mailing list. (I shall not identify it. The author deserves praise for his/her contribution, not a public mauling, and the reason for the message is that that package is not unusual.) The reason I chose it was that I thought actually, I should learn how to use that, never mind the students. Upon looking at the Haddock web page, - reaction one this is pretty flashy. - reaction two, but WHERE IS THE DOCUMENTATION? These are good points and I agree with the rest of your email as well (which I've removed for the sake of brevity). However, I would like to offer two qualifiers that I myself have found when writing documentation for my own libraries: * When writing the code, it's obvious what it does; as such you may think any documentation you may offer is trivial (down the track, however...). * The author is familiar with a library; as such it may not be obvious what extra documentation could be needed. As such, if you're a user of a library and you think it's documentation could be improved, maybe try telling the maintainer that (this kind of prompting is why I bothered to make a website for my graphviz library). As a kind of a wishlist, having more markup support would possibly improve the quality of documentation (rather than being limited to normal text, monospace text and italic text; I've often times wanted to make something bold in my Haddock documentation to emphasise it but alas Haddock doesn't support it). -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] creating documentation links failed with cabal install --haddock-options=--hyperlink-source. is this a bug?
On Sat, 2009-10-31 at 10:45 -0500, Thomas Hartman wrote: cabal haddock -–hyperlink-source installs documentation with links to source code, which also be on by defualt. cabal install –haddock-options=–hyperlink source does not install hyperlinked source. This is an instance of the lack of the feature described in this ticket: http://hackage.haskell.org/trac/hackage/ticket/517 BTW, you're getting confused between flags for the cabal haddock command and the haddock command. The --hyperlink-source flag is for the cabal haddock command. The haddock tool has no such flag (or anything equivalent) so using --haddock-options= will not help. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)
On a somewhat related note, I think the Haskell documentation in general is rather patchy and hard to follow for most things. Part of that I think is because of the confusion between the different forms of documentation. In general as a programmer I expect to find three kinds of documentation available, preferably in a centralized location, but at least in a handful of standardized locations. The first kind, is what Haskell has in abundance, and what is hosted in Hackage, which is API documentation. API documentation is written to be terse, to assume you already know how library Foo works (and probably library Bar and Baz too), and you just need to refresh yourself on exactly what the signature of function wibble was exactly. Really good API documentation also fills the role of some of the other kinds of documentation and has some quick examples sprinkled around the most commonly used functions and maybe a nice intro paragraph with even more examples and some suggestions for further information. The second kind of documentation which is very nearly non-existant for most Haskell packages is a user manual that documents in detail all the functions and data types of a package, how you use them, and the ideas and concepts they're based on. Given only this documentation, a firm understanding of the language, and a basic knowledge of the problem domain, anyone should be able to write an application using your library. If they have to spend three hours trying to track down some obscure research paper that's referenced in your documentation a half dozen times in as many functions, you're not providing enough detail and assuming too great a knowledge of the domain. The last kind of documentation which is fortunately somewhat more prevalent then the previous kind is the classic tutorial, which documents and thoroughly explains the most commonly used functions in your library (not to be confused with thoroughly explaining your library which is the job of the user manual). There are quite a few good tutorials on Haskell in general, Monads specifically, and a lot of random bits and pieces floating around on the net, and thankfully collected for reference on the Haskell wiki. On the whole, the Haskell API docs are decent (although most of them are not what I would call Good), and the tutorials are also rather plentiful, but the user manuals are practically non-existent. What would be ideal is if the hackage entry for each package also included a link to the user manual for that package if it exists (and hopefully most of them would exist) in addition to the links to the API docs and homepage it already has (I suppose in theory the homepage link can serve this purpose and in some cases it currently does, but an actual manual link would be nice). (All of the following were chosen at random) For reference, here is a good example of an API doc: http://hackage.haskell.org/package/zlib Average API docs (but with links to good user manual and tutorial): http://hackage.haskell.org/package/DeepArrow Bad API docs (but once again with a link to average manual/tutorial): http://hackage.haskell.org/package/actor -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Mon, Oct 12, 2009 at 16:29, John Lato jwl...@gmail.com wrote: From: Derek Elkins derek.a.elk...@gmail.com On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett iainsp...@gmail.com wrote: On 11 Oct 2009, at 13:58, John Lato wrote: For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have? John Lato P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm. You could say that about most documentation (for Haskell and beyond). Apparently, programmers like programming better than documenting. The effect of this is that less people use their programming, making their efforts redundant. Silly really, considering programmers are (allegedly:) intelligent. Apparently, programmers like programming better than reading as well... in my experience. I won't disagree. But I think the real difficulty is that the intersection of programmers who can come up with really good ways to solve problems (not even all programmers, unfortunately) and people who are good at writing documentation is vanishingly small. It seems to me that when someone works in a problem domain (e.g. Generic Programming), they gain a very deep understanding of that area and are used to working at a certain level within it. When introducing the topic to newcomers (even ostensibly smart programmers)
Re: [Haskell-cafe] Re: Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)
On Mon, Oct 19, 2009 at 4:32 PM, Kyle Murphy orc...@gmail.com wrote: If they have to spend three hours trying to track down some obscure research paper that's referenced in your documentation a half dozen times in as many functions, you're not providing enough detail and assuming too great a knowledge of the domain. Even just a paragraph or two giving some background information and example use cases would help immensely here; sometimes I just want to quickly assess whether a library might be useful for solving a particular problem, and go read this paper stops me cold. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Installing documentation with cabal
It is. From command line: cabal install package --enable-documentation or add line documentation: True to .cabal/config or equivalent. Best regards Krzysztof Skrzętnicki On Tue, Aug 18, 2009 at 22:29, Maciej Piechotka uzytkown...@gmail.comwrote: Is it possible to automatically (or non-automatically) install documentation when installing package with cabal-install? Regards ___ 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] Installing documentation with cabal
On Tue, 2009-08-18 at 22:37 +0200, Krzysztof Skrzętnicki wrote: It is. From command line: cabal install package --enable-documentation or add line documentation: True to .cabal/config or equivalent. Best regards Krzysztof Skrzętnicki Thanks a lot. Regards 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] Re: Documentation on hackage
who needs this kind of documentation? http://hackage.haskell.org/packages/archive/tfp/0.2/doc/html/Types-Data-Num-Decimal-Literals.html The code below is shown under 'Source' links in that documentation. I don't understand it, but it seems everything is generated automatically. What should the author do to avoid those comments? Older versions of haddock used to define a CPP constant that could be used to tweak the code for haddock. Since newer versions nominally support every feature that GHC supports, that CPP support was dropped. (a) it would be nice if haddock still identified itself via CPP, just like GHC does. Then users would at least have the option to work around current limitations / bugs in haddock, as well as present tweaked presentations of their interfaces. (b) it seems sensible for haddock to provide two options for handling template Haskell code: - document the TH code - document the code generated by TH In this case, the first option would seem more suited. Claus module Types.Data.Num.Decimal.Literals where import Types.Data.Num.Decimal.Literals.TH import Types.Data.Num.Decimal.Digits import Types.Data.Num.Ops $( decLiteralsD D d (-1) (1) ) -- ___ 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] Slow documentation generation on Hackage
On Jun 8, 2009, at 04:10 , Niemeijer, R.A. wrote: Hence I wanted to ask if this is a bug or if there is a good technical or social reason for it, and whether there is any way around it. Auto-running haddock on upload strikes me as a good way to open hackage.haskell.org to a denial of service attack. Additionally, I *think* haddock is run as part of the automated build tests, which (again) happen on a regular schedule instead of being triggered by uploads to avoid potential denial of service attacks. -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH PGP.sig 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] Slow documentation generation on Hackage
On Jun 8, 2009, at 04:36 , Brandon S. Allbery KF8NH wrote: On Jun 8, 2009, at 04:10 , Niemeijer, R.A. wrote: Hence I wanted to ask if this is a bug or if there is a good technical or social reason for it, and whether there is any way around it. Auto-running haddock on upload strikes me as a good way to open hackage.haskell.org to a denial of service attack. I should clarify: yes, in a valid project haddock takes almost no time. Nevertheless: (1) if many uploads of even valid packages are made in a very short time, the system load could well be severely impacted; (2) what of malicious packages, which might trigger bugs in haddock leading to (say) 100% CPU loops? That we don't know of any doesn't mean there aren't any, unless the test suite is absolutely 100% complete (and for a large program, that becomes as hard to verify as the program itself. now consider that haddock is part of ghc these days...). -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH PGP.sig 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] Slow documentation generation on Hackage
If that is the main concern, would the following not work? - Hackage accounts already have to be created manually, so there is no chance of a DDoS. - Uploading to hackage requires a username and password, which means the user can be identified. Set a timeout on uploads for each user: packages sent within 2 minutes of the previous one are automatically refused. Prevents quantity-based DoS. - Generate haddock docs immediately on upload, but apply a 2-second timeout; if it takes longer, the process is killed and no documentation is generated. Prevents exploit-based DoS. - If many valid packages are uploaded in a short time (though I have my doubts as to how often that is going to happen), put them in a queue. Documentation will take a bit longer to generate, but the server can control the load. Prevents inadvertent DoS. Result: immediate documentation for every contributor with good intentions (which, face it, is going to be all of them; I doubt Haskell is popular enough yet to be the target of DoS attacks) and no possibility for DoS attacks. I might be overlooking something, but I believe this should work just fine. -Original Message- From: Brandon S. Allbery KF8NH [mailto:allb...@ece.cmu.edu] Sent: maandag 8 juni 2009 10:41 To: Brandon S. Allbery KF8NH Cc: Niemeijer, R.A.; haskell-cafe@haskell.org Subject: Re: [Haskell-cafe] Slow documentation generation on Hackage On Jun 8, 2009, at 04:36 , Brandon S. Allbery KF8NH wrote: On Jun 8, 2009, at 04:10 , Niemeijer, R.A. wrote: Hence I wanted to ask if this is a bug or if there is a good technical or social reason for it, and whether there is any way around it. Auto-running haddock on upload strikes me as a good way to open hackage.haskell.org to a denial of service attack. I should clarify: yes, in a valid project haddock takes almost no time. Nevertheless: (1) if many uploads of even valid packages are made in a very short time, the system load could well be severely impacted; (2) what of malicious packages, which might trigger bugs in haddock leading to (say) 100% CPU loops? That we don't know of any doesn't mean there aren't any, unless the test suite is absolutely 100% complete (and for a large program, that becomes as hard to verify as the program itself. now consider that haddock is part of ghc these days...). -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Slow documentation generation on Hackage
Niemeijer, R.A. r.a.niemei...@tue.nl writes: If that is the main concern, would the following not work? [...] Result: immediate documentation for every contributor with good intentions Or simply, on upload, generate the doc directory with a temporary page saying that documentation will arrive when it's good and ready? Result: as before, but with less confusion for new contributors. So not as good as Niemeijer's suggestions, but probably easier to implement. -k -- If I haven't seen further, it is by standing in the footprints of giants ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Slow documentation generation on Hackage
On Mon, Jun 8, 2009 at 11:05, Niemeijer, R.A.r.a.niemei...@tue.nl wrote: which, face it, is going to be all of them; I doubt Haskell is popular enough yet to be the target of DoS attacks Second that. I think this is a good case in which some security should be traded in for usability. And even if a DoS attack occurs, it just causes some downtime... not unlike the certain hours of downtime that the documentation currently has. If there's actually an exploitable leak in Haddock that allows the server to be compromised (not just DoSed), then the current Haddock generation is just as vulnerable. But of course I'm not the maintainers of Hackage... it's up to them to decide. Thomas ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Slow documentation generation on Hackage
Thomas ten Cate wrote: Niemeijer, R.A. wrote: which, face it, is going to be all of them; I doubt Haskell is popular enough yet to be the target of DoS attacks Second that. I think this is a good case in which some security should be traded in for usability. Those who would trade security for usability deserve neither usability nor security ;) Seriously, all the Haskell hackers I've encountered have been good people, but Haskell is the language of the hair shirt afterall. Security is hard enough to come by in the first place, sacrificing what little we have is not the right path. The Haskell interwebs are already too susceptible to downtimes from non-malicious sources, and it floods #haskell whenever it happens. I agree that the turnaround time is a bit long, but I think server stability is more important than instant feedback. It's easy enough to get an account on community.haskell.org and just upload your own docs there[1]. The thing I'd be more interested in getting quick feedback on is whether compilation succeeds in the Hackage environment, which is very different from my own build environment. Given the various constraints mentioned, and depending on the load averages for the servers, perhaps the simplest thing to do would be to just reduce the latency somewhat. Flushing the queue every 4~6 hrs seems both long enough to circumvent the major DoS problems, and short enough to be helpful to developers. Especially if the queue could be set up to be fair among users (e.g. giving each user some fixed number of slots or cycles per flush, delaying the rest until the next cycle). A different approach would be to do exponential slowdown per user. So if a user has submitted N jobs in the last Window (e.g. 24 hours), then the job is run around Epsilon^N after submission (where Epsilon is, say, 3 minutes). [1] I do: http://community.haskell.org/~wren/ The scripts to automate it are trivial, but I can share them if people like. -- Live well, ~wren ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Slow documentation generation on Hackage
On Mon, 2009-06-08 at 11:24 +0200, Ketil Malde wrote: Niemeijer, R.A. r.a.niemei...@tue.nl writes: If that is the main concern, would the following not work? [...] Result: immediate documentation for every contributor with good intentions Having the server generate docs itself would be regressing towards a worse design. The server should just manage upload/download, storage and management of information. It should not be running builds and generating docs. Or simply, on upload, generate the doc directory with a temporary page saying that documentation will arrive when it's good and ready? And use a design where there isn't just a single build client, like the design for the new hackage-server. Any authorised client should be able to upload docs. That should include the package maintainer as well as authorised build bots. Then we can easily adjust the time between package upload and documentation generation without having to tell the server anything. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Slow documentation generation on Hackage
On Mon, Jun 08, 2009 at 04:36:14AM -0400, Brandon S. Allbery KF8NH wrote: Additionally, I *think* haddock is run as part of the automated build tests, which (again) happen on a regular schedule instead of being triggered by uploads to avoid potential denial of service attacks. That's correct. One workaround is to upload your package just before 0:00, 6:00, 12:00 or 18:00 UK time. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation for Haddock
2009/2/27 Colin Paul Adams co...@colina.demon.co.uk: On http://haskell.org/haddock/doc/html/module-attributes.html the not-home attribute is missing (it's documentation is present, but the attribute itself is not named). Thanks for the report. By the way, the Haddock trac page is at: http://trac.haskell.org/haddock We also have a mailing list: hadd...@projects.haskell.org I will fix this bug directly, so we don't need a bug ticket of course. But it may be nice for you to know where to report bugs in the future. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] IntMap documentation error
On Mon, 2009-02-23 at 17:22 -0600, Louis Wasserman wrote: In the documentation for Data.IntMap updateMin, a piece of example code both communicates incorrect intuition, and fails to even compile. updateMin :: (a - a) - IntMap a - IntMap a updateMin (\ _ - Nothing) (fromList [(5,a), (3,b)]) -- code straight from the docs interactive:1:49: Couldn't match expected type `Maybe a' against inferred type `[Char]' In the expression: a In the expression: (5, a) In the first argument of `fromList', namely `[(5, a), (3, b)]' As a side note, the sort of operation implied by the example code was really what I was looking for in the documentation -- but such a method no longer exists in IntMap. ::sad:: Who do I tell this to / how do I ask to get it fixed? Open a ticket in the ghc trac: http://hackage.haskell.org/trac/ghc/ set the component to libraries other. Paste in your description and if you can, attach a darcs patch to the ticket. More generally, to work out where to send things check the hackage page. Most packages list a maintainer or author and some are now specifying a bug reports url. Currently for the containers package it's not all that helpful, it only lists a maintainer email address as librar...@haskell.org. Though that would also have been a place to start to get the above advice. The next release of all the core packages will also list their bug-report urls and these will appear on their hackage pages. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] about documentation improvements
On Fri, 2009-01-16 at 15:12 +0100, Manlio Perillo wrote: About latest thread on better naming and documentation improvement, why don't organize an interactive session where: 1) normal users tell what's wrong about a package/module documentation 2) the package/module author/maintainer fix the documentation in real time, so that users can review it again Along similar lines, here's a project I've been thinking about that someone might like to try... It's a cross between darcs and a wiki. You want to let users contribute minor fixes to code or documentation. It's especially relevant for trivial changes to documentation. But instead of making the change live, it makes a darcs patch and sends it to the package maintainer. The point is it should be as easy as a wiki to make some minor improvement, but it does not mean your actual source code lives in a wiki, the maintainer still has control and gets patches via their normal source control system. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] about documentation improvements
On Fri, Jan 16, 2009 at 03:12:21PM +0100, Manlio Perillo wrote: About latest thread on better naming and documentation improvement, why don't organize an interactive session where: 1) normal users tell what's wrong about a package/module documentation 2) the package/module author/maintainer fix the documentation in real time, so that users can review it again Not quite real time, the documentation generated by the nightly builds should be at http://www.haskell.org/ghc/dist/current/docs/libraries/index.html It doesn't seem to have been updated since 7 Jan, though. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] about documentation improvements
-BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On Fri, Jan 16, 2009 at 9:29 AM, Duncan Coutts wrote: On Fri, 2009-01-16 at 15:12 +0100, Manlio Perillo wrote: About latest thread on better naming and documentation improvement, why don't organize an interactive session where: 1) normal users tell what's wrong about a package/module documentation 2) the package/module author/maintainer fix the documentation in real time, so that users can review it again Along similar lines, here's a project I've been thinking about that someone might like to try... It's a cross between darcs and a wiki. You want to let users contribute minor fixes to code or documentation. It's especially relevant for trivial changes to documentation. But instead of making the change live, it makes a darcs patch and sends it to the package maintainer. The point is it should be as easy as a wiki to make some minor improvement, but it does not mean your actual source code lives in a wiki, the maintainer still has control and gets patches via their normal source control system. Duncan Now that Gitit supports a Darcs-backend, maybe Gitit would work. The idea is one would do a darcs get of whatever library, mv it into a gitit dir/, and then run gitit in dir/. Now there's a web interface which lets people edit any repo-tracked file (dir/repo/*). Of course, there's nothing stopping users of that wiki from editing stuff besides the haddocks (although one certainly hopes they will stick to doc changes). But here's the cool part: because each wiki edit is a full-fledged patch, and the wiki's dir/repo/ is presumably tracking the main library repo, any patch from the wiki should be directly applicable to the main library repo. So then someone can, every day or two, visit the wiki and review all the patches. He obliterates the bad ones, and he will either darcs push or darcs send all the good ones to the main repo! This proposal has the advantage of being extremely easy to set up and run, easy to understand (this here wiki is an exact copy of the real repo; if we like your changes, we'll copy them over to the real repo after a day or 2. Now run along and have fun.), and still permitting as much review as the conventional lumbering process. And it also has scope for additional capabilities. Perhaps one would add a post-commit-hook which does a darcs send of all new patches to a mailing list. Or perhaps Gitit could display Haskell src files as Haddock pages only so an editor could make little tweaks, hit the 'preview' button, and see whether he fixed whatever. Or... - -- gwern -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) iEYEAREKAAYFAklwqZcACgkQvpDo5Pfl1oIxEgCeJkKE+uGsjw2Yb3rIRolaam7e aagAnR4yDKJ7e3QI8MEzwQtSYT43oPUF =4JXN -END PGP SIGNATURE- ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] about documentation improvements
Duncan Coutts ha scritto: On Fri, 2009-01-16 at 15:12 +0100, Manlio Perillo wrote: About latest thread on better naming and documentation improvement, why don't organize an interactive session where: 1) normal users tell what's wrong about a package/module documentation 2) the package/module author/maintainer fix the documentation in real time, so that users can review it again Along similar lines, here's a project I've been thinking about that someone might like to try... It's a cross between darcs and a wiki. You want to let users contribute minor fixes to code or documentation. It's especially relevant for trivial changes to documentation. But instead of making the change live, it makes a darcs patch and sends it to the package maintainer. That's what I was thinking, documentation behind a revision control system. However I was thinking of: - normal user can only add annotations - only authors can change the documentation The point is it should be as easy as a wiki to make some minor improvement, but it does not mean your actual source code lives in a wiki, the maintainer still has control and gets patches via their normal source control system. I was not thinking of a wiki; but of a system to be used for small sessions (about 1/2 hour) held once in a while, where there is strong interaction between users and authors. Manlio Perillo ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] FFI documentation?
Nun Aurbiz wrote: Where do I find the documentation for the FFI for GHC? I've read the FFI report, the GHC user guide and scoured haskell.org but they all gloss over what commands you actually need to give GHC and how to give them. foreign import blah blah just gives me undefined references. I've documented some of manual building in an old post on FFI http://therning.org/magnus/archives/238 Not sure if it's enough to get you on your way though... /M -- Magnus Therning (OpenPGP: 0xAB4DFBA4) magnus＠therning．org Jabber: magnus＠therning．org http://therning.org/magnus Haskell is an even 'redder' pill than Lisp or Scheme. -- PaulPotts signature.asc Description: OpenPGP digital signature ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] FFI documentation?
2008/11/8 Nun Aurbiz [EMAIL PROTECTED]: Where do I find the documentation for the FFI for GHC? I've read the FFI report, the GHC user guide and scoured haskell.org but they all gloss over what commands you actually need to give GHC and how to give them. foreign import blah blah just gives me undefined references. You need to give the libraries you are using on the command line just like gcc. ghc --make Foo -lbar Luke ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock documentation of Data.Array.* is confusing
Hello Alfonso, Tuesday, February 12, 2008, 11:32:20 PM, you wrote: Excuse me for the subject, but IMHO is absolutely true. Anyhow, the of course, you are right, but for practical goals i may suggest just to read module sources instead of reading [had]docs. seeing the implementation is much more interesting, after all. especially when you are so cool that you are going to add your own instance -- Best regards, Bulatmailto:[EMAIL PROTECTED] ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock documentation of Data.Array.* is confusing
On Wed, Feb 20, 2008 at 10:17 PM, Bulat Ziganshin [EMAIL PROTECTED] wrote: Hello Alfonso, Tuesday, February 12, 2008, 11:32:20 PM, you wrote: Excuse me for the subject, but IMHO is absolutely true. Anyhow, the of course, you are right, but for practical goals i may suggest just to read module sources instead of reading [had]docs. Well, that's what I was forced to do in the end, but I still think that the haddock documentation should be clear enough for most of the cases, and, when it comes to Data.Array* it could certainly be improved. seeing the implementation is much more interesting, after all. especially when you are so cool that you are going to add your own instance I don't think that being cool had anything to do with it. My only purpose was to understand the desing of the interface for inmutable arrays. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] array documentation is missing
On 14 Dec 2007, [EMAIL PROTECTED] wrote: but I got stuck fixing it because the array documentation isn't there http://www.haskell.org/ghc/docs/latest/html/libraries/haskell98/Array.html Try the hierarchical library docs: http://haskell.org/ghc/docs/latest/html/libraries/array/Data-Array-MArray.html http://haskell.org/ghc/docs/latest/html/libraries/array/Data-Array-ST.html Jed pgpjdAkVLycE4.pgp Description: PGP signature ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Andrew Coppin wrote: OTOH, I recently discovered that GHCi has the ability to show you what's defined in a given module without me having to wait 40 seconds for Firefox to start... Shame you can't scroll its output. (And still no help if you're not sure of the module name.) !!! Run ghci in an environment with a scroll buffer then? Like a non-braindead terminal application, or emacs? (The latter even gives you convenient reverse-incremental-search to search through the info you just printed) Jules ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Jules Bean wrote: Andrew Coppin wrote: OTOH, I recently discovered that GHCi has the ability to show you what's defined in a given module without me having to wait 40 seconds for Firefox to start... Shame you can't scroll its output. (And still no help if you're not sure of the module name.) !!! Run ghci in an environment with a scroll buffer then? Like a non-braindead terminal application, or emacs? (The latter even gives you convenient reverse-incremental-search to search through the info you just printed) I don't know if Andrew is a windows user, but if so he might not be aware that even with the (otherwise braindead) command window the number of lines buffered is a configurable property (on WinXP at least). I have it set to 1000 lines. The other thing I've found that makes the use of command line tools a lot less painful than it would otherwise be in windows is the Open Command Window Here Power Toy.. http://www.microsoft.com/windowsxp/downloads/powertoys/xppowertoys.mspx It's still nowhere near as good as the old XTree though :-( Regards -- Adrian Hey ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
On Sunday 09 September 2007 18:41, Andrew Coppin wrote: [...] Well, if I could collapse it with a single click, it would be much easier to scroll past it and get to the thing I'm looking for. I didn't say remove it, just give me the option to hide it. ;-) OK, that shouldn't be too hard to implement. Oh goodie... So it's there to keep the machines happy? No, it's there to keep *me* happy when I'm looking for a module. ;-) It's just tedious that every single time I load up this page, I have to spend 30 seconds manually collapsing everything so I can get to the module I actually want to look at. (The alternative is to manually scroll the 13-page list my hand. Not very funny...) I still fail to understand why you have to scroll or collapse manually, every browser I know of has a search facility. And there is the index page, where you have an incremental search facility even when your poor browser (guess which one I mean? :-) doesn't have it, at least when the index has been generated by a recent Haddock. OK, so... can we add a pair of expand all/collapse all buttons then? Again, this should be rather easy to add. Cheers, S. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Neil Mitchell wrotes : Replicating actual tables with CSS is a nightmare - you shouldn't use table's for lots of things, I agree but there are sometimes when it really is the best option. Which isn't the case here ! Nested lists would easily do the trick... Fixing up the CSS and still keeping tables is a perfectly valid option. yes it's true... E.D ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Just bookmark: http://haskell.org/hoogle It's not perfect, but it probably solves lots of your problems. And if you use Firefox, you can even install Hoogle as one of the search engines in the upper-right search box. Nice and fast! -Brent ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Sven Panne wrote: On Sunday 09 September 2007 18:41, Andrew Coppin wrote: Oh goodie... So it's there to keep the machines happy? No, it's there to keep *me* happy when I'm looking for a module. ;-) Well, there's over 200 modules relating to graph theory alone. (Modules that I will never ever need, since I don't even know what graph theory *is*...) There's also a few hundred OpenGL modules - which I won't be looking at unless I specifically want to do something with OpenGL... In summary, it's probably quicker to be able to just expand the ones I want to look at, rather than collapse the ones I don't want to look at. (Works for Windows Explorer and the file system, eh?) I still fail to understand why you have to scroll or collapse manually, every browser I know of has a search facility. And there is the index page, where you have an incremental search facility even when your poor browser (guess which one I mean? :-) doesn't have it, at least when the index has been generated by a recent Haddock. I dislike searches. When all the categories are collapsed, they fit onto a single page. The hierachy is sufficiently shallow that from there you can instantly get to any module. And if you can't remember the exact name of the module, searches are useless but you can probably find it visually in a few clicks. OTOH, I recently discovered that GHCi has the ability to show you what's defined in a given module without me having to wait 40 seconds for Firefox to start... Shame you can't scroll its output. (And still no help if you're not sure of the module name.) If you're really stuck, there's always Hoogle. Assuming you can guess either the likely function name or the correct order and type of its arguments... (And on occasion it has a habit of not showing the function you're looking for, or just showing it very far down the list, even though the type signature *exactly* matches what you typed... but usually it's quite good.) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Brent Yorgey wrote: And if you use Firefox, you can even install Hoogle as one of the search engines in the upper-right search box. Nice and fast! I've never really understood what the benefit of this is... I mean, Google make the Google toolbar, but what's the point? Why not just click on the Google bookmark and type in your search? What benefits does installing a special addon provide? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
On Sun, Sep 09, 2007 at 05:38:03PM +0200, Sven Panne wrote: On Sunday 09 September 2007 16:40, Andrew Coppin wrote: I have the following page bookmarked: http://haskell.org/ghc/docs/latest/html/libraries/ I'd like to ask 2 things. 1. Would it be possible to make the *huge* list of package names at the top collapsable? (That way I don't have to scroll through several pages of uninteresting text to get to the bit I actually want.) What do you mean exactly with the *huge* list of package names? The description list with the short textual descriptions of each package? It's about a fifth of the page, I think, and it'll get larger percentagewise as base breaks up more. Also, on Debian systems, we add all installed libraries to this index, so it gets even larger. I'd say that this list is highly interesting to people unfamiliar with the package structure, so it is good that it is there. Is that really helpful? There isn't a mapping from package name to modules, so I'm not sure what it buys you. I'm sure I've never looked at it. I'm interested in other opinions on this, as I planned to remove the list from the Debian packages. Would it be better to have a separate page with a package index, containing the description of each package and a link to each of the modules that it provides? Thanks Ian ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
On Mon, 2007-09-10 at 20:28 +0100, Ian Lynagh wrote: Would it be better to have a separate page with a package index, containing the description of each package and a link to each of the modules that it provides? +1 ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
On Mon, 2007-09-10 at 19:51 +0100, Andrew Coppin wrote: Brent Yorgey wrote: And if you use Firefox, you can even install Hoogle as one of the search engines in the upper-right search box. Nice and fast! I've never really understood what the benefit of this is... I mean, Google make the Google toolbar, but what's the point? Why not just click on the Google bookmark and type in your search? What benefits does installing a special addon provide? Well, for the default Google searchbox the advantage is: Ctrl-K search phrase ENTER versus grab mouse .. point ... click ... move hand back to keyboard ... type search phrase, ENTER I never used any of the secondary search bars. Unless I can define a shortcut to access hoogle quickly there's no advantage. However, regarding the modules list. I think it should be easy to have optional javascript functionality to toggle the visibility of the module tree. The default visibility could be customized using a cookie. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Hi I've never really understood what the benefit of this is... I mean, Google make the Google toolbar, but what's the point? Why not just click on the Google bookmark and type in your search? What benefits does installing a special addon provide? You can setup firefox so in the location bar (Alt+D) typing h query (without the quotes) will perform a hoogle query. Simply right click in the search box and click add keyword search with h as the keyword. You can also do the same for Google, which I've been using for years (Opera 5 had this feature!) re: Hoogle not always getting it exactly right, there are a few known bugs floating around which I'm working on. Hoogle can permute the order of arguments though, so that shouldn't be a problem. It doesn't really like Monads, but I wrote Hoogle before I was aware of higher-kinded type classes, so its understandable... Thanks Neil ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Well, for the default Google searchbox the advantage is: Ctrl-K search phrase ENTER versus grab mouse .. point ... click ... move hand back to keyboard ... type search phrase, ENTER I never used any of the secondary search bars. Unless I can define a shortcut to access hoogle quickly there's no advantage. To search Hoogle I just type Ctrl-K F4 h search phrase ENTER. Once you're in the search box, F4 (or alt-up/alt-down) let you select a particular search engine. -Brent ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Neil Mitchell wrote: Hi re: Hoogle not always getting it exactly right, there are a few known bugs floating around which I'm working on. Hoogle can permute the order of arguments though, so that shouldn't be a problem. It doesn't really like Monads, but I wrote Hoogle before I was aware of higher-kinded type classes, so its understandable... Overall, I think Hoogle is an increadibly neat tool. I've never seen anything else like it. (But then, how many other languages let you virtually figure out what a function does just by its type signature?) I shudder to think what Hoogle will be like if they ever get round to adding MPTCs, ATs, rank-Ns and existential types to the language standard... Good luck with searching for that! ;-) OOC, how big is Hoogle and how long did it take to do? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
I agree about the top part. It's not very interesting, especially not in a document used as a reference. Perhaps we could move it to the end and provide an anchor link from the different modules down to their package explanation. A tip is to use Firefox's search as you type feature if you know the module name. Cheers, Johan On 9/9/07, Andrew Coppin [EMAIL PROTECTED] wrote: I have the following page bookmarked: http://haskell.org/ghc/docs/latest/html/libraries/ I'd like to ask 2 things. 1. Would it be possible to make the *huge* list of package names at the top collapsable? (That way I don't have to scroll through several pages of uninteresting text to get to the bit I actually want.) 2. Could we make is so all items are collapsed initially? (Currently they're all expended initially - which makes it take rather a long time to find anything.) Just thought I'd ask... ___ 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] Tiny documentation request
On Sunday 09 September 2007 16:40, Andrew Coppin wrote: I have the following page bookmarked: http://haskell.org/ghc/docs/latest/html/libraries/ I'd like to ask 2 things. 1. Would it be possible to make the *huge* list of package names at the top collapsable? (That way I don't have to scroll through several pages of uninteresting text to get to the bit I actually want.) What do you mean exactly with the *huge* list of package names? The description list with the short textual descriptions of each package? I'd say that this list is highly interesting to people unfamiliar with the package structure, so it is good that it is there. 2. Could we make is so all items are collapsed initially? (Currently they're all expended initially - which makes it take rather a long time to find anything.) Again this depends on the use case: I'd vote strongly against collapsing the list initially, because that way the incremental search in Firefox won't work without un-collapsing everything. When the index is generated with a more recent Haddock, you get a search field, which does an incremental search, so this might perhaps be more what you are looking for. A more aesthetical note: We should really get rid of the ugly table/CSS layout mixture, the lower part of the page renders a bit ugly and varies between browsers. Switching to pure CSS should be safe in 2007, I guess. Cheers, S. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Sven Panne wrote: On Sunday 09 September 2007 16:40, Andrew Coppin wrote: 1. Would it be possible to make the *huge* list of package names at the top collapsable? (That way I don't have to scroll through several pages of uninteresting text to get to the bit I actually want.) What do you mean exactly with the *huge* list of package names? The description list with the short textual descriptions of each package? I'd say that this list is highly interesting to people unfamiliar with the package structure, so it is good that it is there. Well, if I could collapse it with a single click, it would be much easier to scroll past it and get to the thing I'm looking for. I didn't say remove it, just give me the option to hide it. ;-) 2. Could we make is so all items are collapsed initially? (Currently they're all expended initially - which makes it take rather a long time to find anything.) Again this depends on the use case: I'd vote strongly against collapsing the list initially, because that way the incremental search in Firefox won't work without un-collapsing everything. Oh goodie... So it's there to keep the machines happy? It's just tedious that every single time I load up this page, I have to spend 30 seconds manually collapsing everything so I can get to the module I actually want to look at. (The alternative is to manually scroll the 13-page list my hand. Not very funny...) OK, so... can we add a pair of expand all/collapse all buttons then? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Tiny documentation request
Hi I have the following page bookmarked: http://haskell.org/ghc/docs/latest/html/libraries/ Just bookmark: http://haskell.org/hoogle It's not perfect, but it probably solves lots of your problems. A tip is to use Firefox's search as you type feature if you know the module name. This will be better supported in Hoogle 4 - but unfortunately degrees etc. are coming in the way of Hoogle development... A more aesthetical note: We should really get rid of the ugly table/CSS layout mixture, the lower part of the page renders a bit ugly and varies between browsers. Switching to pure CSS should be safe in 2007, I guess. Replicating actual tables with CSS is a nightmare - you shouldn't use table's for lots of things, but there are sometimes when it really is the best option. Fixing up the CSS and still keeping tables is a perfectly valid option. Thanks Neil ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Text.XHtml Documentation
You can often find old webpages at web.archive.org: http://web.archive.org/web/20070406145557/http://www.cse.ogi.edu/~andy/html/intro.htm Searching, with part of the text, revealed that you can also find this page at: http://search.cpan.org/src/AUTRIJUS/Language-Haskell-0.01/hugs98-Nov2003/fptools/hslibs/text/html/doc/doc.htm -- Met vriendelijke groet, Henk-Jan van Tuyl -- http://functor.bamikanarie.com http://Van.Tuyl.eu/ -- On Sat, 28 Jul 2007 08:01:35 +0200, Dean Herington [EMAIL PROTECTED] wrote: The Haddock documentation for Text.XHtml (at http://www.haskell.org/ghc/docs/latest/html/libraries/xhtml/Text-XHtml.html) refers to http://www.cse.ogi.edu/~andy/html/intro.htm, but that link is broken. Does anyone know where to find the intended document? On Sun, 29 Jul 2007 17:14:24 +0200, David F. Place [EMAIL PROTECTED] wrote: Hello: I was just looking into using Text.XHtml for a project. The Haddock documentation points to an introduction by Andy Gill, but the link is broken. Can anyone point me to the correct location of the introduction? Thanks. Cheers, David ___ (---o---o-o-o---o-o-o( David F. Place mailto:[EMAIL PROTECTED] ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] NDP documentation
Andrew, Actually, I was just reading through all the Data Parallel Haskell and Nested Data Parallelism documentation. It says in several places that parallel array comprehensions are available since GHC 6.6, but they are broken; please use the development versions; this will be fixed in GHC 6.6.1. Can anybody clarify - was this actually fixed? (And shouldn't somebody update the Wiki?) Yes, the problems were fixed in 6.6.1 as promised. I just forgot to update the wiki when 6.6.1 was released (now done). Thanks for the reminder. Manuel ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] NDP documentation
Bulat Ziganshin wrote: Hello Andrew, Monday, July 23, 2007, 11:50:32 PM, you wrote: Actually, I was just reading through all the Data Parallel Haskell and Nested Data Parallelism documentation. It says in several places that parallel array comprehensions are available since GHC 6.6, but they are broken; please use the development versions; this will be fixed in GHC 6.6.1. parallel arrays (GHC.PArr) was implemented at least in ghc 6.4 and my program using it was worked fine with 6.4.*, 6.6 and 6.6.1 now. but i don't use comprehensions, only !: operator To my utter frustration, Thunderbird is once again refusing to download the message I actually want to reply to, but anyway... Acording to the wiki, the parallel array stuff has two halves. First, there's the parallel array library that does all the good stuff, and then there's a seperate library that gives you all the nice syntax sugar. (I.e., parallel array comprehensions.) Automatic transformation from one to the other is not yet implemented. So at the moment, you can try out the neat new syntax - but it won't actually run in parallel - or you can play with the low-level stuff. The wiki also says that the parallel array comprehensions are buggy in GHC 6.6, and you should use HEAD until GHC 6.6.1 comes out. Well, 6.6.1 *is* out now, so I'm wondering if somebody should change the information on the wiki? Also, while I'm here... Why hasn't the automatic conversion been done yet? Is it because nobody has had time, or is it because there's an actual problem? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] NDP documentation
Hello Andrew, Monday, July 23, 2007, 11:50:32 PM, you wrote: Actually, I was just reading through all the Data Parallel Haskell and Nested Data Parallelism documentation. It says in several places that parallel array comprehensions are available since GHC 6.6, but they are broken; please use the development versions; this will be fixed in GHC 6.6.1. parallel arrays (GHC.PArr) was implemented at least in ghc 6.4 and my program using it was worked fine with 6.4.*, 6.6 and 6.6.1 now. but i don't use comprehensions, only !: operator -- Best regards, Bulatmailto:[EMAIL PROTECTED] ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
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
