April 2010 - web-devel

web-routes-quasi
by Michael Snoyman 17 Apr '10

17 Apr '10

web-routes-quasi is now at the point where it can be used for sites, and I'd love to hear some feedback. I've put together a little sample that demonstrates how you can use quasi-quoting and define your routes, embed subsites and serve the resulting application via WAI. (My example uses WAI, but the package itself is not tied to WAI.) The code is on github[1]; the main function for the blog is in blog.hs (with the lowercase b). I believe this just depends on Jeremy's web-routes package, wai and wai-extra. Note that I did not use web-routes-wai; I think there are some problems in there for breaking up the pathinfo, and I didn't have time to dig through it. Also, this package currently ignores entirely the defaultPage component of Site, though if there is desire support can be added for it. One minor bug is that you can't have an alternate GET, POST, PUT or DELETE constructor imported; hopefully that will get cleaned up. Any comments and suggestions are welcome! My goal is to port Yesod over to this as soon as the web-routes set of packages are released, so if you're interested in Yesod, you should be interested in this too ;). Michael [1] http://github.com/snoyberg/web-routes-quasi

4 15

Re: [web-devel] Re: The state of documentation
by Michael Snoyman 13 Apr '10

13 Apr '10

I'm torn on this one. I'm not going to bother retroactively doing documentation for 0.0.0; however, once I release 0.2.0, and I work on 0.4.0, I'd like people to have access to documentation on released code as well as development code. I'm not quite certain... As far as that intro page, I was providing that table more as a comparison, but I think I'll be removing it entirely. Michael On Tue, Apr 13, 2010 at 1:18 PM, Thomas Hartman < thomashartman1(a)googlemail.com> wrote: > It looks great. > > My only possible nit is that it seems odd to include docu for 0.0.0 as > well as 0.0.2, why not just do the latest and let the past be done? > > On Tue, Apr 13, 2010 at 12:54 PM, Michael Snoyman <michael(a)snoyman.com> > wrote: > > > > > > On Fri, Apr 9, 2010 at 8:06 AM, Michael Snoyman <michael(a)snoyman.com> > wrote: > >> > >> > >> On Fri, Apr 9, 2010 at 3:32 AM, Gour <gour(a)gour-nitai.com> wrote: > >>> > >>> On Fri, 9 Apr 2010 08:36:51 +0200 > >>> >>>>>> "Simon" == Simon Hengel wrote: > >>> > >>> Simon> My feeling is that we lack mostly short, tutorial-style > >>> Simon> introductions, that just get you started with a topic/library. > >>> > >>> I agree. > >>> > >>> Moreover, practically every 'framework' (except Happs) is more or less > >>> one-man show band, i.e. it works for their authors without docs, but > >>> that's not the way one can build community around it...And without > >>> some 'critical' mass of users, one is reluctant to invest time/energy > >>> into such products...Kind a catch-22. :-( > >>> > >>> > >> I can't speak for others, but I personally don't have a problem > investing > >> in documentation on my one-man-show libraries. In the specific case of > >> Yesod, I *know* it's going to have some major changes in the next > release, > >> so it's not worth it right now. > >> In general, I think the problem for library writers is that- since *we* > >> wrote the code- we don't know what's confusing about it. As far as we're > >> concerned, our code is beautiful, elegant, simple and self-documenting > >> (until we look at it again six months later). We really need an outside > >> voice to tell us what's lacking. > >> So instead of saying "fizzbuzz has no documentation," maybe say "I saw > the > >> fizzbuzz tutorial on creating foobars, but I couldn't figure out how to > >> extend that for wibbles. Could you write a tutorial for that?" > >> > > So I finally decided to start on the documentation front. Thanks to > everyone > > who's kicked me to get it done, and thanks in particular to Gour for > > reviewing some of it for me. I'll be placing on Yesod-related > documentation > > on a new site: > > http://docs.yesodweb.com/ > > I'm using Hakyll to generate the site, which is working very nicely. The > > code is all available on github (http://github.com/snoyberg/yesoddocs) > so > > if anyone wants to make changes, you can either e-mail me or send a > patch. > > It's not *quite* as nice as a wiki for collaboration, but hopefully will > be > > easier to follow. > > Next goal will be to put up docs on web-routes-quasi. > > Michael > > _______________________________________________ > > web-devel mailing list > > web-devel(a)haskell.org > > http://www.haskell.org/mailman/listinfo/web-devel > > > > > > > > -- > Need somewhere to put your code? http://patch-tag.com > Want to build a webapp? http://happstack.com >

1 0

What frameworks are there?
by Kyle Murphy 13 Apr '10

13 Apr '10

I'm looking at experimenting with developing a site and due to various constraints I'm considering using one of the haskell frameworks. I experimented a bit with Happstack, although I'm not all that happy with it and I'm interested in alternatives. I've also looked briefly at yesod but it doesn't seem to be very well documented and I've got some concerns. The environment I'm working in has constrained memory, about 300M physical, with a further 500M of swap, but a relatively beefy CPU, so I'm trying to stay away from any of the in memory systems like MACID in happstack. At this point I'm mostly toying with the different frameworks to try to get a feel for them, but in a couple months I'm probably going to need to actually put together a production system that can handle some fairly low duty e-commerce. I'm planning on using Google Checkout for order processing, but aside from that and the memory constraints I don't have any real hard rules for what the framework needs to support. I'm currently running nginx to serve static content on the server, so I could potentially integrate with that, or I could just have whichever framework I end up using serve the static content as well. So, my requirements are as follows: 1) Small memory footprint 2) Relatively simple to extend such that I can integrate it with Google Checkout 3) Documented well enough that I can figure out how to plumb everything together without needing to dig through the guts of the framework 4) Relatively stable such that a year from now I don't need to re-write the entire site because the framework isn't maintained an no longer works on the current version of GHC. Any suggestions? P.S. I'm interested in the quasi-quote package I saw mentioned here recently, but it looks more suited for use by framework developers rather than as a finished component, at least from the limited info I've found. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

8 21

Re: [web-devel] Re: The state of documentation
by Kyle Murphy 13 Apr '10

13 Apr '10

Thanks for the feedback. The original docs can be found here ( http://hackage.haskell.org/package/xhtml-3000.2.0.1 ). The changes I added at this point are exclusively in the main description of the Text.XHtml, Text.XHtml.Table, Text.XHtml.Strict, Text.XHtml.Transitional and Text.XHtml.Frameset modules. For the Strict, Transitional, and Frameset modules the only changes from the original is a blurb about checking the main Text.XHtml package for detailed documentation. As for tutorial.happstack.com, no, I don't think that's an example of a "bad tutorial", nor was I complaining that the tutorials available for Haskell are in general bad. My complaint is more that the tutorials can only really be responsible for covering so much material at which point the core documentation (either the auto-generated stuff on hackage, or some other source that's mostly non-existent right now) needs to take up the slack. Text.XHtml is relatively simple, so I was able to provide the kind of documentation it needs directly in the haddock, but for larger non-trivial libraries we really need some kind of standardized location for documentation. Ideally wherever that is should also be intergrated into hackage somehow, as hackage is where most newbies are going to go looking for packages, and the documentation of said packages. That being said, there's currently discussion going on in the other mailing lists about modifications to Hackage to add better support for documentation in general, and user contributed documentation in particular, so maybe it's just a matter of time. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Tue, Apr 13, 2010 at 14:51, Thomas Hartman <thomashartman1(a)googlemail.com > wrote: > Hi Kyle, > > On the whole I am always thrilled when someone works to improve the > haskell docu, particularly in the web space. > > I am the author of tutorial.happstack.com, which I admit might be an > example of the type of "bad" tutorials you write of, which > nevertheless fill a necessary gap during documentation coallescence. > > The reason I didn't give you any feedback is there wasn't an > easy/fast way for me to see what changes you had made, other than > flipping back and forth from your docu to the original docu, and I'm > not even sure where the existing docu is -- hackage I suppose. > > If you had used github or (plug) patch-tag, you might have gotten > more feedback, or even if you had just (re)stated the type of changes > you had made. > > Anyway thank you for working to improve the state of haskell on web > docu, and of course, contribute back to the xhtml maintainers. > > Cheers, thomas. > > > > On Tue, Apr 13, 2010 at 6:56 AM, Kyle Murphy <orclev(a)gmail.com> wrote: > > I haven't received any response on this at all so far, which I'm not sure > > how to interpret. Does everyone think I should submit the updated > > documentation to the maintainer of the xhtml package, or is there some > issue > > someone would have with seeing these changes in the official > distribution? > > I'm also not sure I'm completely done updating the docs, I'd like to see > > some better documentation on the actual functions themselves as well, and > > I'll probably do that before submitting it as a patch. > > > > -R. Kyle Murphy > > -- > > Curiosity was framed, Ignorance killed the cat. > > > > > > On Sat, Apr 10, 2010 at 03:16, Kyle Murphy <orclev(a)gmail.com> wrote: > >> > >> I managed to find some time to put together an example update of the > >> documentation for xhtml package with the sorts of changes I'd like to > see > >> applied to as much of hackage as possible. You can find the updated > haddock > >> at http://tenletters.org/haddock/index.html > >> > >> Depending on the feedback I get on this updated documentation I might > try > >> to get in touch with the xhtml maintainer and have my changes merged in > to > >> the official repository. Let me know what you guys think. > >> > >> -R. Kyle Murphy > >> -- > >> Curiosity was framed, Ignorance killed the cat. > >> > >> > >> On Fri, Apr 9, 2010 at 15:02, Kyle Murphy <orclev(a)gmail.com> wrote: > >>> > >>> That blog post was excellent and fairly well captures the spirit of > what > >>> I was getting at, although I do disagree somewhat about the > auto-generated > >>> docs. I don't have any problem with auto-generated docs in and of > >>> themselves, assuming that you also insert into that documentation the > sort > >>> of details discussed in the "topic guides". A great example of this is > most > >>> of the POD used in Perl modules, where at least the first few > paragraphs of > >>> documentation are typically devoted to essentially being a "topic > guide" for > >>> that module. I think what she was really complaining about in that post > is > >>> exactly the situation we have in hackage currently where there is for > all > >>> intents and purpose absolutely no documentation provided for the vast > >>> majority of libraries beyond the automatically generated signatures and > the > >>> odd sentence or two. > >>> > >>> Something I'd like to see become common in haddock is for instance, a > >>> good general description, with references to sub-modules in the main > module > >>> of a package. Each sub-module would then function as a topic guide for > the > >>> features of that module, with the specific API details contained in the > >>> function descriptions. If I have some time this weekend maybe I'll pull > down > >>> the source for Text.XHTML, and try to update its documentation to > provide an > >>> example of what I'm getting at. > >>> > >>> -R. Kyle Murphy > >>> -- > >>> Curiosity was framed, Ignorance killed the cat. > >>> > >>> > >>> On Fri, Apr 9, 2010 at 14:36, Gour <gour(a)gour-nitai.com> wrote: > >>>> > >>>> On Fri, 9 Apr 2010 14:07:28 -0400 > >>>> >>>>>> "Kyle" == Kyle Murphy wrote: > >>>> > >>>> Kyle> The next highest level of documentation, what's severely lacking > >>>> Kyle> in the Haskell community in general, and the web development > >>>> Kyle> community in particular, is the in depth documentation for the > >>>> Kyle> libraries/frameworks. These documents aren't quite tutorials, > >>>> Kyle> but they go beyond just telling you the minimal information you > >>>> Kyle> need to use a function. This sort of document would typically > >>>> Kyle> have a section for each of the major use cases of your > >>>> Kyle> framework/library, and possibly a few brief code snippets > >>>> Kyle> showing how you go about doing particular things. For instance, > >>>> Kyle> in the Text.XHTML package, this document would most likely list > >>>> Kyle> the various functions for generating html elements like br, as > >>>> Kyle> well as have a section talking about the attribute op (!), the > >>>> Kyle> Html concatination op (+++), and the Html nesting op (<<), and > >>>> Kyle> provide examples of how to construct a few example pages. It's > >>>> Kyle> this level of documentation that's really missing, and where > >>>> Kyle> most people would head to once they finish following along on > >>>> Kyle> some tutorial. > >>>> > >>>> If we consider that Django is nicely documented and can be used as > >>>> example, do you think about stuff called 'topic guides' listed at > >>>> > >>>> http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext > >>>> > >>>> i.e. something in between tutorial and API reference? > >>>> > >>>> Here is blog post about it: > >>>> > >>>> http://jacobian.org/writing/great-documentation/what-to-write/ > >>>> > >>>> Kyle> As a final thought, haddock itself might even be leveraged to > >>>> Kyle> provide this higher level documentation, it certainly has the > >>>> Kyle> capability of doing so, it just generally isn't used in that > way. > >>>> Kyle> The brief summary most people put at the top of the generated > >>>> Kyle> haddock, which usually consists of a one or two sentence > >>>> Kyle> description of what the library provides, could instead be used > >>>> Kyle> to provide details of all the use cases, and links to the > >>>> Kyle> appropiate pieces of documentation. > >>>> > >>>> Long ago I was suggesting on 'cafe' that it would be nice if the > >>>> haddock documentation would have some 'examples of usage', but it > >>>> looks it is too much and we are still far from it... > >>>> > >>>> > >>>> Sincerely, > >>>> Gour > >>>> > >>>> -- > >>>> > >>>> Gour | Hlapicina, Croatia | GPG key: F96FF5F6 > >>>> ---------------------------------------------------------------- > >>>> > >>>> _______________________________________________ > >>>> web-devel mailing list > >>>> web-devel(a)haskell.org > >>>> http://www.haskell.org/mailman/listinfo/web-devel > >>>> > >>> > >> > > > > > > _______________________________________________ > > web-devel mailing list > > web-devel(a)haskell.org > > http://www.haskell.org/mailman/listinfo/web-devel > > > > > > > > -- > Need somewhere to put your code? http://patch-tag.com > Want to build a webapp? http://happstack.com >

1 0

A separation of concerns
by Chris Eidhof 05 Apr '10

05 Apr '10

Hi everyone, I don't believe that there could be one big framework for everybody. Some people want good HTML abstractions, others only think of the server as data storage. Some people want RESTful URLs, other people don't care about RESTfulness but would benefit heavily from controller abstractions. For certain applications SQL might be perfect and for others the Happstack-State works great. My point is: we should not try to build one big framework. Instead, I propose that we build a set of smaller libraries that each do one thing very well. Some of these libraries might be designed to work together. I personally think MVC is a perfect fit for the web: model code handles data storage, view code handles HTML/JSON/XML and the controller coordinates between these. Instead of building packages that do all of these things, I would like to see model packages, view packages and controller packages. That way we can achieve maximum reusability and a good separation of concerns. What do you think of this? -chris

11 20

WAI 0.2.0 begun
by Michael Snoyman 04 Apr '10

04 Apr '10

Well, to follow up on the WAI improvement thread: I've just pushed the first commit for WAI 0.2.0; this commit makes request and response headers case-insensitive. I'm in no rush to make this release, so if anyone has some changes they'd like to see, please let me know (are just send a patch). http://github.com/snoyberg/wai Michael

1 0

Type-safe URL handling
by Chris Eidhof 03 Apr '10

03 Apr '10

Hey everyone, I just wrote down some of my ideas about type-safe URL handling on github, it's at http://gist.github.com/333769 I think it's similar to what Jeremy is doing with his urlt package [1]. -chris [1]: http://src.seereason.com/~jeremy/SimpleSite1.html

5 68