<br><div class="gmail_quote">On Nov 16, 2007 5:31 PM, Andrea Rossato <<a href="mailto:mailing_list@istitutocolli.org">mailing_list@istitutocolli.org</a>> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="Ih2E3d">On Fri, Nov 16, 2007 at 01:46:46PM -0800, Don Stewart wrote:<br>> One issue: why not develop this on the wiki, rather than in a src file?<br>> I didn't understand the motivation there.<br><br>
</div>The idea is to use haddock for editing purposes. That module should be<br>a high level access to each module documentation. This was the idea.<br>Not a tutorial or a wiki page.<br><br>But, as I said, this is just a proposal. If you believe a wiki page
<br>would better fit our purposes we can get rid of this module and<br>transfer that content to a wiki page.<br><font color="#888888"><br>Andrea<br></font><div><div></div><div class="Wj3C7c"></div></div></blockquote><br>Here are my thoughts. I think there are really two distinct audiences here, and there should be two distinct documents:
<br><br>1. People who are just trying to configure xmonad.<br><br>I think Documentation.hs is a great document for these people. It should be straightforward, with detailed descriptions of simple things, and a high-level overview of what extension modules are available. A lot of this is already in
Documentation.hs, and it's great. The pro of having this as Haddock-generated documentation (as opposed to on the wiki) is that it can automatically and easily link to the Haddock documentation for other contrib modules, which will automatically be up-to-date; there are no problems with making sure a wiki document stays current and so on. I think it will also encourage developers of new modules to add links to their documentation, since it is all right there in the source (rather than having to remember to edit the wiki separately). And of course we can have a link to it on the wiki.
<br><br>2. People who know a bit of Haskell and want to get a bit fancier with their configuration, or write some new extensions.<br><br>Andrea, it seems that this is the kind of thing you have started putting in Documentation.hs
(starting with the section "Writing new extensions"), but I think this should probably go on the wiki instead. The problem is that I think this document, written properly, will be VERY long! <br><br>I actually care very much about such a document and have a great vision of what it could be, since I essentially started writing such a document a couple months ago! I started going through the xmonad source in order to understand it, and, encouraged by Don, began writing an 'xmonad commentary'. I already have a bunch of commentary on StackSet, but have put it on hold due to grad school apps, the big changes with
0.5, and so on. Hopefully sometime soon I will have a chance to upload what I have to the wiki so that others can work on it too. My vision for this commentary is that someone who knows some basic Haskell could read it and come away with (a) a much deeper understanding of Haskell and the sorts of techniques that are used; (b) an excitement for Haskell and what it makes possible, with xmonad as a case study; and (c) (last but not least) the ability to contribute new extension modules and so on.
<br><br>-Brent<br><br><br></div>