Kyle,<div><br></div><div>You&#39;re 100% correct about the state of documentation. I think we need to figure out a nice, centralized place to put up quality Haskell documentation, and actually work at it.</div><div><br></div>
<div>The obvious place is the Haskell wiki, but a downside is that many people do not have accounts. For github projects- like Yesod- we could use the wiki pages there, but that&#39;s not exactly standardized.</div><div><br>
</div><div>In addition, I think it will help library authors to know *where* the documentation is lacking. For example, I know that I haven&#39;t written much documentation on the Handler datatype in Yesod. However, I&#39;m not sure if anyone actually *cares* about that, or if instead a nice introduction to the authentication framework would be more welcome.</div>
<div><br></div><div>I assume we won&#39;t come up with any great solutions to the documentation issue in the immediate future; in the interim, if people want to see some documentation on any of my packages, please do one of the following:</div>
<div><br></div><div>* File an issue on the appropriate github projects making a request for documentation. Be as clear as possible.</div><div>* Start a Wiki page (either Github or Haskell wiki) with your questions and e-mail me to let me know it&#39;s there.</div>
<div>* Send an e-mail to the web-devel list with the question.</div><div>* As a last resort, e-mail me privately. I&#39;d much prefer that these discussions happen in public so that others can learn and contribute.</div><div>
<br></div><div>I&#39;m more than open to better suggestions. I&#39;ll also appreciate any help in improving my documentation.</div><div><br></div><div>Michael</div><div><br><div class="gmail_quote">On Thu, Apr 8, 2010 at 11:07 AM, Kyle Murphy <span dir="ltr">&lt;<a href="mailto:orclev@gmail.com">orclev@gmail.com</a>&gt;</span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">I guess my biggest problem with the state of web development in Haskell as it currently stands is that there&#39;s no good easily accessible tutorials on how to go about doing things. There are lots of example programs scattered around, and some of them are even documented reasonably well that you can look at them and sort of figure out how they go together using the various pieces, but once you try to go beyond those specific bits and pieces you end up wandering off into the weeds. What I&#39;m looking for most of all is one set of documentation I can look through and figure out how to put a simple application together that supports handling GET/POST requests, storing and retrieving session info, and ideally a simple long term storage solution such as HSQL.<br>

<br>Right now I feel like just to put together a simple page that handles form submission I need to have mastered 4 or 5 different libraries, all documented in different locations. When I first started trying to do web development in Haskell I looked at the Happstack tutorials, and that worked fairly well, I was able to take a simple paste bin application and modify it to add some javascript into the generated page, however even that fairly trivial modification meant I had to go digging through the Text.XHTML documentation, which consisted solely of the automaticlly generated hadock. Furthmore I&#39;m still not entirely sure how the various pieces of Happs actually fit together, or what pieces are provided by Happs, and what pieces are provided by other external libraries. Yesod is a similar situation in which I&#39;m not entirely sure what&#39;s provided where and where to go to find the documentation of that. I&#39;m sure an expert Haskell developer can just glance over the hadock for a library and figure out how to put all the pieces together, but as a Haskell newbie I often get lost trying to figure out how to do things that in other languages would be fairly trivial. Most of the time when I&#39;m lost on how to do something it isn&#39;t even because what I want to do is terribly difficult, it&#39;s just that the documentation on how to do something assumes that you essentially already know how to do it and are just looking for clarrification on the details, a situation that I usually resolve by either trial and error, or by looking for some piece of code somewhere that does what I want and trying to puzzle out how it actually goes about doing that.<br>

<br>Part of this seems to be caused by most of the libraries/frameworks being documented solely in hadock, which is ok for a quick reference, but sucks for trying to learn how to use a library/framework. Even though it&#39;s true there&#39;s a lot of usefull info contained in just the signature of a function, if that&#39;s the first time you&#39;ve been exposed to that function and aren&#39;t entirely sure of its purpose, that information isn&#39;t enough to really understand the function, at least for non-trivial functions. The big frameworks like Happs, Turbinado, and hopefully soon Yesod, do seem to be fairly well documented, but the fact that they&#39;re built on top of a bunch of the other libraries like HSQL, HStringTemplate, and Text.XHTML that aren&#39;t well documented undermines the ability to fully understand them, as before you can really make the most use out of their documentation you must first go puzzle your way through the poor documentation of all the support libraries.<br>

<br>Further complicating matters is the scattered way in which libraries are documented. For all I know, there&#39;s really excellent documentation for Text.XHTML, but just looking at it on hackage, and a quick google search doesn&#39;t seem to reveal anything particularly useful. The hackage page for Text.XHTML has a link for more info, but going to the page that supposedly contains more info I&#39;m greeted with a 404 page. It would be one thing if this was the exceptional case, but from what I&#39;ve seen that&#39;s pretty much par for the course.<div class="im">
<br>
<br clear="all">-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br><br></div><div><div></div><div class="h5"><div class="gmail_quote">On Thu, Apr 8, 2010 at 10:15, Sebastiaan Visser <span dir="ltr">&lt;<a href="mailto:sfvisser@cs.uu.nl" target="_blank">sfvisser@cs.uu.nl</a>&gt;</span> wrote:<br>
<blockquote class="gmail_quote" style="border-left:1px solid rgb(204, 204, 204);margin:0pt 0pt 0pt 0.8ex;padding-left:1ex">
Kyle,<br>
<br>
What functionality do you need? What do you want this `framework&#39; to offer you? There are plenty of packages for Haskell that help you to write web applications, all of them offering some functionality. It&#39;s very unlikely you&#39;ll find one single package that satisfies all your requirements.<br>


<br>
I advice you to look around and see what package there are and how these might help you.<br>
<br>
For example, I&#39;m currently thinking about building a web application using:<br>
  - The Salvia server interface (not surprisingly, this one is written by me)<br>
  - The Haskell bindings to the Berkeley XML database for long-term storage.<br>
  - The Salvia-session package for in-memory session storage.<br>
  - The HXT xml library.<br>
  - The regular-xmlpickler for generic XML printing/parsing (using HXT picklers).<br>
  - The BlazeHtml package for building up HTML pages (fast).<br>
  - The formlets package for generating flexible web forms.<br>
  - The CleverCSS package (and salvia integration) for improved css support.<br>
  - probably even more...<br>
<br>
Although I agree it is not always easy to get a grip on what are the best techniques available for Haskell web development, there are plenty of tools available. It will probably take some time to get to know all these libraries, but due to the clear separation of concerns and Haskell&#39;s neat type system, integration is almost never a problem.<br>


<br>
I sincerely hope this might help you and does not scare you :-)<br>
<br>
Regards,<br>
<font color="#888888"><br>
Sebastiaan<br>
</font><div><div></div><div><br>
On Apr 8, 2010, at 3:29 PM, Kyle Murphy wrote:<br>
&gt; -R. Kyle Murphy<br>
&gt; --<br>
&gt; Curiosity was framed, Ignorance killed the cat.<br>
&gt;<br>
&gt;<br>
&gt; On Thu, Apr 8, 2010 at 04:17, Alistair Bayley &lt;<a href="mailto:alistair@abayley.org" target="_blank">alistair@abayley.org</a>&gt; wrote:<br>
&gt; Uh...<br>
&gt;<br>
&gt; &gt;From <a href="http://hackage.haskell.org/packages/pkg-list.html#cat:web" target="_blank">http://hackage.haskell.org/packages/pkg-list.html#cat:web</a><br>
&gt;<br>
&gt; 1. happs<br>
&gt; 2. yesod<br>
&gt; 3. hack<br>
&gt; 4. salvia<br>
&gt; 5. kibro<br>
&gt; 6. hsp  (barely a framework, I think)<br>
&gt;<br>
&gt; From the descriptions of those all but kibro, and happs/yesod which have been mentioned, I would classify as bits of frameworks, rather than a full framework like happs or yesod. Kibro looks interesting, but I can&#39;t find any documentation at all but the rather meager hadoc info on hackage itself, which tells me next to nothing about the framework. It also looks like Kibro is a CGI framework and not a full application server.<br>


&gt;<br>
&gt; Other frameworks not on hackage, possibly not under active development:<br>
&gt;<br>
&gt; 7. hvac ( <a href="http://fmapfixreturn.wordpress.com/2008/03/23/ann-hvac-01b-a-transactional-declarative-framework-for-lightweight-web-applications/" target="_blank">http://fmapfixreturn.wordpress.com/2008/03/23/ann-hvac-01b-a-transactional-declarative-framework-for-lightweight-web-applications/</a><br>


&gt; )<br>
&gt; 8. turbinado ( possibly abandoned: <a href="http://github.com/alsonkemp/turbinado" target="_blank">http://github.com/alsonkemp/turbinado</a> )<br>
&gt; 9. WASH  ( <a href="http://www.haskell.org/haskellwiki/WaSh" target="_blank">http://www.haskell.org/haskellwiki/WaSh</a> ,<br>
&gt; <a href="http://www.informatik.uni-freiburg.de/%7Ethiemann/WASH/" target="_blank">http://www.informatik.uni-freiburg.de/~thiemann/WASH/</a> )<br>
&gt;<br>
&gt; Hadn&#39;t heard of Turbinado and I&#39;m checking that out now (it at least has some documentation even if a few of the links seem to be broken). WASH likewise looks interesting, although I&#39;m not terribly thrilled about using CGI (I will if I have to, but I&#39;d be more comfortable with a full application server). hvac looks like it has potential, although the lack of documentation probably means I won&#39;t be using it.<br>


&gt;<br>
&gt; There are some other bits which don&#39;t qualify as full frameworks, but<br>
&gt; might well be useful in their own right:<br>
&gt;<br>
&gt;  - HStringTemplate<br>
&gt;  - formlets<br>
&gt;<br>
&gt; And there&#39;s bound to be stuff that I&#39;ve missed.<br>
&gt;<br>
&gt; Alistair<br>
&gt;<br>
&gt; Yes, and I&#39;ve actually looked at both HStringTemplate and formlets (briefly) with the idea to either use them in conjunction with one of the other frameworks (Yesod I know uses HStringTemplate, at least for the moment, and I think Happs has some integration with formlets).<br>


&gt;<br>
&gt; As was mentioned by Gour in another followup to this, there&#39;s also Hakyll, which is an interesting possibility, but I&#39;m not sure I&#39;d be happy with the result. In particular it would ruin my plans for integrating with Google Checkout as I was planning on using the server side XML interface.<br>


&gt;<br>
&gt; Based on the feedback I&#39;ve gotten so far, my list of possibilities in order of preferance seems to be:<br>
&gt; 1) Yesod<br>
&gt; 2) Turbinado (might change, need to look at this more)<br>
&gt; 3) Happs<br>
&gt; 4) WASH<br>
&gt; 5) Hakyll (if I can stomache using static generation)<br>
&gt; 6) All the poorly documented ones like hvac, and kibro<br>
&gt; 7) Roll my own out of the various pieces<br>
&gt;<br>
<br>
</div></div></blockquote></div><br>
</div></div><br>_______________________________________________<br>
web-devel mailing list<br>
<a href="mailto:web-devel@haskell.org">web-devel@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/web-devel" target="_blank">http://www.haskell.org/mailman/listinfo/web-devel</a><br>
<br></blockquote></div><br></div>