As a product of the discussions we (mainly me and Apfelmus) had over the last few threads I created a "List of topics" page in http://en.wikibooks.org/wiki/Haskell/List_of_topics . It is a simple presentation of the key topics covered by the book modules with occasional comments. The intention is to make picturing the structure of the book and brainstorming about large-scale reorganizations easier. As of now it covers only "Haskell Basics", "Elementary Haskell" and "Intermediate Haskell". If you find the list useful feel free to discuss book structure in its talk page, expand it to cover the advanced chapters or make test edits to visualize the effects of changes to the book organization. Regards, Daniel Mlot
Daniel Mlot wrote:
As a product of the discussions we (mainly me and Apfelmus) had over the last few threads I created a "List of topics" page in http://en.wikibooks.org/wiki/Haskell/List_of_topics . It is a simple presentation of the key topics covered by the book modules with occasional comments. The intention is to make picturing the structure of the book and brainstorming about large-scale reorganizations easier. As of now it covers only "Haskell Basics", "Elementary Haskell" and "Intermediate Haskell". If you find the list useful feel free to discuss book structure in its talk page, expand it to cover the advanced chapters or make test edits to visualize the effects of changes to the book organization.
I've added the new structure for "Haskell Basics" as I envision it, neatly put into a table next to the old one. I'm still a bit hazy on the cheat sheet chapter, because it needs to do several things simultaneously: * introduce each category and mention which functions are important and which are not; pointing to more detailed discussion for lists and IO * present a quick overview list of the functions * give a slightly more detailed account of each function The idea is that the reader is given some exercises and he'll have to hunt the right functions for these tasks. There is no need to organize the advanced chapters in detail, they are only loosely coupled anyway; they can be interchanged freely. Regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
On 05/13/2010 07:34 AM, Heinrich Apfelmus wrote:
I've added the new structure for "Haskell Basics" as I envision it, neatly put into a table next to the old one.
It looks sound. Next step is considering how the "Elementary" / "Intermediate" modules would have to change to accommodate the reshuffle. (By the way, I like your preference of guards and where over if, case and let for the "Basics" - not only because they are the simpler, but also because they are more distant from the usual procedural syntax, thus helping a bit to push newbies towards a paradigm shift.)
I'm still a bit hazy on the cheat sheet chapter, because it needs to do several things simultaneously:
* introduce each category and mention which functions are important and which are not; pointing to more detailed discussion for lists and IO * present a quick overview list of the functions * give a slightly more detailed account of each function
The idea is that the reader is given some exercises and he'll have to hunt the right functions for these tasks.
I set up a mock-up cheat sheet at http://en.wikibooks.org/wiki/Haskell/Experimental_Modules/Cheat_sheet_protot... . I structured it thinking on one appendix (or several ones) linked from the main "Building a vocabulary" module, where the more verbose discussions would be. The infrastructure could be easily adapted to different schemes, of course. Writing good and precise one-line descriptions of functions can be tricky (for instance, in my examples I don't like the way I described the folds and scans), but at least it looks neat. Regards, Daniel Mlot
Daniel Mlot wrote:
Heinrich Apfelmus wrote:
I'm still a bit hazy on the cheat sheet chapter, because it needs to do several things simultaneously:
* introduce each category and mention which functions are important and which are not; pointing to more detailed discussion for lists and IO * present a quick overview list of the functions * give a slightly more detailed account of each function
The idea is that the reader is given some exercises and he'll have to hunt the right functions for these tasks.
I set up a mock-up cheat sheet at http://en.wikibooks.org/wiki/Haskell/Experimental_Modules/Cheat_sheet_protot... . I structured it thinking on one appendix (or several ones) linked from the main "Building a vocabulary" module, where the more verbose discussions would be. The infrastructure could be easily adapted to different schemes, of course. Writing good and precise one-line descriptions of functions can be tricky (for instance, in my examples I don't like the way I described the folds and scans), but at least it looks neat.
PS: Apfelmus: Nice thought to have added examples to the cheat sheets. I only fear they can grow a bit too wide sometimes, but in such cases nothing stops us from putting a "see on the detailed explanation" note there :)
An example is worth more than a hundred words. ;) I think they make excellent one-line explanations. In fact, I'm unsure whether it's a good idea to write more detailed explanations at all, I'd rather link to the official documentation for that. Also, I'm unhappy with the current markup we have to use. It's much easier to specify it in "pseudo haddock markup" -- | Last element. -- > last [1,2,3] = 3 last :: [a] -> a -- | Number of elements. -- > length [True, False] = 2 length :: [a] -> Int and have a Haskell program translate that to wikitext or any other format. Regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
Hello, I took a bit of a break from the book over this week in order to give time to my ideas to get clearer. By the way, I just reduced my Haskell naivety a bit by writing an useful-ish standalone "real world" program, which works fine other than for being very memory hungry (still, the code is *so* much nicer to work with than the corresponding procedural implementations that I would gladly concede it a couple hundred megabytes to play with). Anyway... On 05/17/2010 11:41 AM, Heinrich Apfelmus wrote:
An example is worth more than a hundred words. ;) I think they make excellent one-line explanations. In fact, I'm unsure whether it's a good idea to write more detailed explanations at all, I'd rather link to the official documentation for that.
I agree to your feelings about detailed explanations; writing them would likely be a boring and potentially pointless task. Replacing the wikilinks in the table with auto-generated links to the docs can probably be done in a reasonably painless way with an extra template.
Also, I'm unhappy with the current markup we have to use. It's much easier to specify it in "pseudo haddock markup"
-- | Last element. --> last [1,2,3] = 3 last :: [a] -> a
-- | Number of elements. --> length [True, False] = 2 length :: [a] -> Int
and have a Haskell program translate that to wikitext or any other format.
That would be an interesting possibility for generating the tables... too bad we can't shortcut around the MediaWiki interface, and would likely still have to rely on it (and its hideous triple-curly-bracket syntax) for maintenance of the cheat sheets after they are uploaded. By the way, that reminds me I used to have a neat Firefox add-on which allowed to edit the contents of any text area into vim; it could become handy in such circumstances. By the way, a note about the chapters: I am missing a bit of doing some actual writing, so if I feel brave enough I will try to contribute to some of the missing bits of Basics. The most likely targets for me would be the initial explanation of numerical types in "Type basics" or some of the list comprehension introduction that will become "Working with lists". Regards, Daniel Mlot
Daniel Mlot wrote:
I took a bit of a break from the book over this week in order to give time to my ideas to get clearer. By the way, I just reduced my Haskell naivety a bit by writing an useful-ish standalone "real world" program, which works fine other than for being very memory hungry (still, the code is *so* much nicer to work with than the corresponding procedural implementations that I would gladly concede it a couple hundred megabytes to play with). Anyway...
Feel free to ask on the #haskell IRC channel or the beginners@haskell.org mailing list for advice on your memory woes; there's always someone around you can help.
Also, I'm unhappy with the current markup we have to use. It's much easier to specify it in "pseudo haddock markup"
-- | Last element. --> last [1,2,3] = 3 last :: [a] -> a
-- | Number of elements. --> length [True, False] = 2 length :: [a] -> Int
and have a Haskell program translate that to wikitext or any other format.
That would be an interesting possibility for generating the tables... too bad we can't shortcut around the MediaWiki interface, and would likely still have to rely on it (and its hideous triple-curly-bracket syntax) for maintenance of the cheat sheets after they are uploaded. By the way, that reminds me I used to have a neat Firefox add-on which allowed to edit the contents of any text area into vim; it could become handy in such circumstances.
I was thinking about putting both the source for the cheat sheet and the Haskell program that translates it on the talk page, and instruct people to make changes there. Not ideal, but should work. Speaking of Haskell program: that would make another good exercise for you, if you're up to it. ;) In the very long run, I'm thinking about moving away from the wikibook technology and creating something with a Haskell backend. This way, we'd have complete freedom to use our own markup and could experiment a little with embedded reader comments and other things. But this is just wishful thinking for now.
By the way, a note about the chapters: I am missing a bit of doing some actual writing, so if I feel brave enough I will try to contribute to some of the missing bits of Basics. The most likely targets for me would be the initial explanation of numerical types in "Type basics" or some of the list comprehension introduction that will become "Working with lists".
Sure, go ahead. :) Regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
On 05/24/2010 09:39 AM, Heinrich Apfelmus wrote:
Daniel Mlot wrote:
I took a bit of a break from the book over this week in order to give time to my ideas to get clearer. By the way, I just reduced my Haskell naivety a bit by writing an useful-ish standalone "real world" program, which works fine other than for being very memory hungry (still, the code is *so* much nicer to work with than the corresponding procedural implementations that I would gladly concede it a couple hundred megabytes to play with). Anyway...
Feel free to ask on the #haskell IRC channel or the beginners@haskell.org mailing list for advice on your memory woes; there's always someone around you can help.
I went to the IRC yesterday. People were quite helpful there but unfortunately we couldn't make a breakthrough before I had to call it a day and have some sleep. On the other hand, all the failed attempts made me able to phrase my issues in a clearer way, so that I can make a comprehensible post in the mailing list.
I was thinking about putting both the source for the cheat sheet and the Haskell program that translates it on the talk page, and instruct people to make changes there. Not ideal, but should work.
This gave me a very cool idea, which is explained in details here: http://en.wikipedia.org/wiki/Wikipedia:Village_pump_(technical)#A_bot_for_me... (I made this post to ask for technical feedback on the MediaWiki side of the things. Also, I mentioned Python, but of course the plan would be interfacing the Haskell parser to the Python MediaWiki API.) Regards, Daniel Mlot
Daniel Mlot wrote:
I was thinking about putting both the source for the cheat sheet and the Haskell program that translates it on the talk page, and instruct people to make changes there. Not ideal, but should work.
This gave me a very cool idea, which is explained in details here:
http://en.wikipedia.org/wiki/Wikipedia:Village_pump_(technical)#A_bot_for_me...
(I made this post to ask for technical feedback on the MediaWiki side of the things. Also, I mentioned Python, but of course the plan would be interfacing the Haskell parser to the Python MediaWiki API.)
Ah, a bot performing the conversion automatically; that would indeed be very useful. Regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
Hello, Just to mention I have added some ideas for "Elementary" and "Intermediate" in the list of topics as well. Alongside some other issues, there are three things for which I can't see an obvious solution. * Can we provide meaningful examples of pattern matching on lists without making use of recursive algorithms? At first I the possibility of moving the "Recursion" chapter to Basics, just after "Tuples and Lists", and use the context to introduce x:xs - but that would kind of defeat the pedagogical proposal of emphasizing function composition before considering in more depth the "inner workings" of functions. The most adequate alternative, then, would be to mention pattern matching on lists only *very* briefly, I guess... (A related observation. Apfelmus' proposal includes a "Working with lists" module in Basics which would be dedicated entirely to list comprehensions. Initially I wondered whether discussing map and filter in that context would be an improvement. Doing so, however, would immediately make it necessary to push, at the very least, "Recursion" to Basics as a prerequisite. Having both map, filter and recursion in Basics would likely make things too clunky. I also wonder if this decision on how far to delve into lists in Basics would have any significant effects in the "Building a Vocabulary" module.) * I am slightly bothered by having "More on Functions" and "Control Structures" only at the end of "Elementary Haskell". "Control Structures" should probably be after "Pattern Matching" anyway, even more so now that we're presenting case structures for the first time. As for "More on Functions", I feel moving it to an earlier point (just after "Recursion", maybe) could improve reading flow (IMO increased alternation of "syntactic" and "conceptual" modules makes for a less tiring read). Furthermore, it would allow us to make occasional use of lambdas, prefixed operators and similar things in the following chapters without worrying with pre-requisites (and, at the same time, helping readers to, through small doses, get used to the syntactic variants). Regards, Daniel Mlot P.S.: Apfelmus: Nice thought to have added examples to the cheat sheets. I only fear they can grow a bit too wide sometimes, but in such cases nothing stops us from putting a "see on the detailed explanation" note there :)
Daniel Mlot wrote:
Just to mention I have added some ideas for "Elementary" and "Intermediate" in the list of topics as well. Alongside some other issues, there are three things for which I can't see an obvious solution.
* Can we provide meaningful examples of pattern matching on lists without making use of recursive algorithms? At first I the possibility of moving the "Recursion" chapter to Basics, just after "Tuples and Lists", and use the context to introduce x:xs - but that would kind of defeat the pedagogical proposal of emphasizing function composition before considering in more depth the "inner workings" of functions. The most adequate alternative, then, would be to mention pattern matching on lists only *very* briefly, I guess...
Yep, it should be mentioned only briefly for lists. However, I am now convinced that pattern matching should be introduced in Haskell Basics. Fortunately, boolean functions make good examples for that.
(A related observation. Apfelmus' proposal includes a "Working with lists" module in Basics which would be dedicated entirely to list comprehensions. Initially I wondered whether discussing map and filter in that context would be an improvement. Doing so, however, would immediately make it necessary to push, at the very least, "Recursion" to Basics as a prerequisite. Having both map, filter and recursion in Basics would likely make things too clunky. I also wonder if this decision on how far to delve into lists in Basics would have any significant effects in the "Building a Vocabulary" module.)
It's possible to introduce map and filter as "black-box" functions and discuss them without recursion. :) In a sense, that's what list comprehensions already do.
* I am slightly bothered by having "More on Functions" and "Control Structures" only at the end of "Elementary Haskell". "Control Structures" should probably be after "Pattern Matching" anyway, even more so now that we're presenting case structures for the first time. As for "More on Functions", I feel moving it to an earlier point (just after "Recursion", maybe) could improve reading flow (IMO increased alternation of "syntactic" and "conceptual" modules makes for a less tiring read). Furthermore, it would allow us to make occasional use of lambdas, prefixed operators and similar things in the following chapters without worrying with pre-requisites (and, at the same time, helping readers to, through small doses, get used to the syntactic variants).
Alternating syntactic and conceptual modules is a good idea. I'm still very hazy on what exactly the "Elementary Haskell" Section should cover. Hopefully, this will become clear after fleshing out the "Haskell Basics". But it's clear that "Recursion" should be at the very top, or even at the end of Haskell Basics. I agree that it's a good idea to put "More on Functions" next. Not sure whether "Pattern matching" should remain intact. The concept itself should be introduced in the "Haskell Basics" already, but I do see the need for a more comprehensive reference, also because it's good for modularity: the reader may have been introduced to pattern matching elsewhere and is now looking for more a comprehensive account of the syntax. There is no harm in repeated explanation, even. In any case, we should link to the corresponding introductory chapter in Haskell Basics. Regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
participants (2)
-
Daniel Mlot -
Heinrich Apfelmus