gmane.comp.lang.haskell.wikibook

One less red link in Haskell Basics

Daniel Mlot — 2012-04-10T02:41:31

Hello,

Since I am doing some moderately large scale changes to the Beginner's 
Track so that we can eventually dispense with that "in reorganization" 
warning on the main page, I guess it is a good idea to write regularly 
to the list so that anyone with an opinion can chime in.

Last week some nice progress (IMHO) was done with the first two parts of 
the Beginner's Trail; and by now I believe a newbie wouldn't find any 
serious breakage disrupting his progress through them. Beyond switching 
the main focus of "Next steps" to a first presentation of pattern 
matching, the other major change was an attempt at writing one of the 
two new pages that Apfelmus, back in 2010 envisioned for Haskell Basics; 
namely, "Building a vocabulary".

My realization of "Building a vocabulary" has the same goal Apfelmus 
originally outlined - making newbies aware of the existence and 
importance of Prelude and the hierarchical libraries. Unfortunately, it 
does so in a chatty rather than practical way. To counter that, we will 
need at least some of the following:

1. the Prelude cheat sheets we talked about in 2010 (see 
http://en.wikibooks.org/wiki/Haskell/Experimental_Modules/Cheat_sheet_prototype_1 
for a rough demo - though by now I believe that the text sections after 
the table are unnecessary);

2. to make better use of the "Libraries Reference" part of Haskell in 
Practice (by completing some pages, making others clearer and providing 
more references to them in the Beginner's Track);

3. more exercises which involve actually using Prelude and the libraries.

Some of these suggestions could be incorporated into "Building a 
vocabulary"; others would fit better being diluted along the Beginner's 
Trail. For the moment, though, I believe the initial version of the new 
page can give newbies some useful pointers.

As usual, it will be most appreciated if you have a few minutes to spend 
reading "Building a vocabulary" and share your opinions on whether the 
advice given is sound, the text is not too boring and the example I made 
up is not too ridiculous.

Regards,

Daniel Mlot

Looking for opinions about "More on Lists" (andhello again!)

Daniel Mlot — 2012-04-04T01:46:09

Hello everybody,

It has been nearly two years since I wrote a flurry of messages to this 
list, while animatedly copy-editing and restructuring the early parts of 
the Wikibook and, alongside Apfelmus, establishing grand plans for a 
reorganization. Regrettably, the energy I had available to back such 
efforts extinguished itself way too quickly...

Anyway, the book-writing bug has just bitten me again, and so over the 
last few nights I worked towards making the early chapters less 
confusing. Things are far from perfect, but I believe they are now 
easier to follow, both for readers and for any contributors trying to 
figure out what is missing. In particular, as far as I can tell the 
creeping problems with chapters having prerequisites found later in the 
book have now been solved.

Beyond telling you of such developments, I also would like to ask for 
your opinion on a specific chapter. Yesterday I reorganized "More About 
Lists" in an attempt to

1. make it into a coherent story - one which starts with the "obvious" 
recursive doubleList and ends with multiplyList n = map ((*) n);

2. give readers an informal, "en passant" primer on what higher-order 
functions are, without getting down to technicalities; and

3. illustrating why map is so useful, of course.

The problem is that now I look at the finished text and worry that the 
"Generalizing even further" section, which prepares the ground for the 
introduction of map (and where most of the higher-order primer is), is 
now too dense in information for a newbie. It would be perfectly 
feasible to avoid most of the higher-order discussion by, immediately 
after the first "real" paragraph, telling it bluntly that "Haskell 
allows us to make our function more general by passing another function 
as argument" and then going straight into the definition of map. (Such 
an approach, by the way, would be much more in line with Apfelmus' plans 
(documented in the list archives from around May 2010), which is a good 
thing as his plans were coherent and had great potential.)

Summing it up, while I think there is some pedagogical value in my 
current approach to "More About Lists", I have serious doubts on whether 
it would work in practice. So I invite you to skim through it and share 
your thoughts on those issues. Your help will be much appreciated.

Regards,

Daniel Mlot

Re: Re: Next steps (both literally and the module)

Daniel Mlot — 2010-06-13T01:42:29

On a general note, these considerations are related to an important 
point about the Wikibook as a whole (or at least my vision for it). One 
important differential of the Beginner's Trail when compared with other 
Haskell tutorials is leanness. The immediate consequence of that is 
practical: For instance, I went through most of it in about ten days, 
and got a reasonably good initial understanding of how Haskell works (at 
least for a complete newbie to functional programming). Certainly things 
wouldn't advance as quickly for me with, say, "Real World Haskell". 
Beyond mere expediteness, however, a book painted with broad strokes 
provide room for readers to complete the picture by acting on their 
curiosity, testing alternatives and developing their personal 
understanding and insights. This approach goes nicely with recognizing 
the "monad tutorial fallacy" and avoid converting analogies and running 
examples into straitjackets. (By the way, I would like to keep those 
things in mind when writing; so if you find any of my texts get bogged 
into excess detail and verbosity please warn me so I can fine tune my 
approach.)

Back to "Type Basics", it seems the underlying problem (or why the text 
doesn't quite fit with the perspectives we are discussing) is the lack 
of strong examples that go beyond the mechanics and illustrate the point 
of having (and taking advantage of) a good type system. Of course, 
whether it is worth it to tackle this conceptual point upfront at such 
an early point (assuming readers with very little experience in 
functional programming) is up for debate.

And finally: I still have not given up completely on that introduction 
:-) Maybe if all references to databases and actual computation are 
removed (retaining only, say, a paper phone book) an useful (or at least 
nice) simple analogy may be presented - one that does not try to explain 
anything concrete, but just provide food for thought. When I feel 
inspired enough I will attempt a draft for you to judge whether my point 
is valid.


Perfect - chances are it will end up being split and redistributed 
between "More on Functions" and "Control Structures", except the part on 
function composition.


I have some ideas on how to do an early introduction to pattern matching 
to put in the slot currently occupied by "Next Steps", and will attempt 
a draft over the following few days.


The general concept of function composition would be key in illustrating 
how important is having a good vocabulary of functions, so it would make 
sense to have it in the cheat sheet module. The usage of the (.) 
operator might be delayed to "More on Functions" if need be.

Regards,
Daniel Mlot

Re: Next steps (both literally and the module)

Heinrich Apfelmus — 2010-06-10T12:37:16

Ah, it's just that in my experience, conceptual explanations usually do
not work so well for introducing someone to a new concept for the first
time. Usually, a hands-on approach that simply uses the concept gives
better results: the student needs to figure out the concept himself, and
usually does so in order to memorize the material anyway.

I think Brent Yorgey has put it most brilliantly in his remark on the
"Monad Tutorial Fallacy":


http://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/

In other words, the concept is synthesized from its particular examples,
not the other way round.


Since the current Next Steps chapter is mainly about the alternative
("expression" vs "declaration") syntax to guards, where, and pattern
matching, it should be moved to the second part of the beginners' track.

Concerning the flow, I think that thanks to the modularity of the
wikibook, we don't need to worry much about it. Simply making a new
chapter on pattern matching seems fine to me.


Either "More on Functions" or the cheat sheet texts, I'd say.


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

Re: Next steps (both literally and the module)

Daniel Mlot — 2010-06-08T06:38:55

I just created the proposed "Type basics II" module. The changes I did 
so far are sort of in between my approach and yours (not that they were 
really in conflict to begin with, but anyway), as I will now explain...


While I agree that the introduction does need streamlining, I am not so 
sure about eliminating it completely, as it can be useful for making it 
easier for readers to amalgamate all the other discussions in this part 
of the book around the key conceptual issue - that types are a way of 
incorporating meaning into values. That is why I kind of like the 
abstract "real world" example, even if in its current form it is a bit 
too overcooked to drive the point home.


Agree about openWindow; it would probably be better if we could find a 
more workable real life example. On the other hand, given that the 
reader is not supposed to know or understand what the types actually are 
anyway, just putting "IO Window" in the signature would be no worse 
than, say, "Foobar" or "Hippogriff" :)


I shortened (though not that much) the final sections so that they could 
fit into the first "Type basics". The detailed rundown of an inference 
example was simplified (so that we are not forced to explain 
polymorphism) and the examples and exercises with forward references 
were eliminated (by the way, I am keeping a copy of deleted sections in 
http://en.wikibooks.org/wiki/User:Duplode/Haskell_leftovers for 
reference and to make eventual reincorporation of materials easier).

As for Type basics II, as of now it is a lightweight discussion on how 
the type system handles numbers, written in a style similar to that of 
Truth values. Typeclasses are introduced, focusing on their implications 
for polymorphism. Some essential "concrete" facilities for number 
manipulation are presented, but for now I am assuming that systematic 
presentation of, say, arithmetic operators will be deferred to the cheat 
sheet modules or similar places.

Finally, a question about Next Steps the module. Do you see a place for 
it in the overall scheme of things? My question is largely motivated by 
the fact I am finding it rather difficult to picture a way to 
incorporate pattern matching into the "soft", largely conceptual modules 
about the type system (I am counting "Truth values" and "Lists and 
tuples" among these) without breaking their flow. That leads me to 
consider introducing piece-wise function definitions or even (x:xs) and 
(x,y) in a separate context. The function composition operator is 
another potentially useful thing in "Next Steps" (because it fits well 
with the idea of stimulating creative usage of Prelude functions) that 
would be difficult to move to an earlier point of the book. That case is 
less serious, though, as there is the option of just moving it to "More 
on Functions".

Regards,
Daniel Mlot

Re: Truth values and a couple other things

Heinrich Apfelmus — 2010-06-03T19:31:43

I like Graham Hutton's way of introducing pattern matching a lot.
(chapter 4.4. of Programming in Haskell). He starts with the obvious

  not False = True
  not True  = False

repeats the "complete case analysis" concept with

  True  && True  = True
  True  && False = False
  False && True  = False
  False && False = False

Then, he introduces wildcards

  True && True = True
  _    && _    = False

and variables

  True  && b   = b
  False && _   = False

as a way to keep the number of cases down. Finally, he mentions the
common pitfall that

  b && b = b
  _ && _ = False

does not work and notes the correct solution

  b && c | b == c    = b
         | otherwise = False


The point is that a handful of simple examples are the most concise and
clear way of introducing pattern matching (or any other concept); there
is no need for "the most general explanation" because humans learn very
well from concrete examples that can be repeated and adapted. (One could
say that this is an instance of the "show, not tell" tenet.)



Sounds good. :)

Personally, I would cut a lot to make it shorter and more "digestible",
though; which might make a split unnecessary. The more elaborate
discussion can always be taken up again in the subsequent "Elementary
Haskell" track.

In other words, I would do the following:

* Cut the introduction. Make  "5 < False  does not make sense" the sole
motivation for types.
* :type is a very useful skill and can stay as it is.
* Ditto for function types, in particular multiple arguments. However, I
think the  openWindow  example is not so good because it's actually a
"pseudo" example; the real example would have to live in the IO monad.
* Replace type signatures and type inference by two very short
paragraphs that basically only say
  "This is what a type signature looks like and you should use it, too."
  "Type inference happens when you don't put a type signature there."


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

Re: Re: Truth values and a couple other things

Daniel Mlot — 2010-06-01T14:56:01

I think I will quote you both in my user page :)


As you probably noticed already, I am slightly more inclined to flowery, 
colourful language. Thankfully as of late I have been able to keep 
myself under check and not get too prolix. In any case, the book would 
certainly profit from some extra conciseness - some existing passages 
grow really tiring just because the same idea is reiterated one time too 
many.

----

About the writing of "Truth Values" and the reworking of "Type Basics" 
(which I started yesterday) there are two main outstanding questions:

1. In "Truth Values" your outline included introducing True/False 
pattern matching when discussing the boolean operators. At first I 
thought it wasn't a good idea, as explained on the Talk page. But now, 
after having a closer look at "Type Basics" and the examples therein, I 
realize that not introducing an idiom this elementary idiom early on 
might be pedagogically problematic, as it may induce newbies to do very 
simple things in obtuse ways (like defining something like (||) with 
guards). In that case, a brief example - with (||), not, etc. could 
easily be added to the Boolean operations section, but I am not sure on 
what would be a clear, simple and not misleading way of introducing 
pattern matching at this point (discussing the general PM concept would 
likely not work, and saying "you can define functions with multiple 
definitions in terms of cases for (quasi-literal?) values of the 
arguments" could get too confusing (mainly the "quasi-literal" part - 
which really means literals and argument-less constructors, but 
obviously we can't go that far at this point of the book).

2. I am starting to believe that "Type Basics" should be divided in two. 
More specifically, the first part would retain the introduction, the 
experiments of :t, the presentation of Char and String and the section 
about functional types. The second part would have the final section 
about type signatures in code and the new section on number types. 
Finally, "Lists and Tuples" would be sandwiched between the two parts. 
Reasons for the splitting include:

* The examples on the final section make use of tuples and string 
concatenation. While we could just reduce them to simple Int/Char/Bool 
functions, I fear that simplifying the examples too much would weaken 
their didactic value in illustrating to readers how signatures are 
important in practice. The move would also help to make the intentional 
forward references in that uppercase example less scary.

* Both the existing demonstration of type inference (which involves the 
signature of (==) ) and the discussions of numerical types involve 
polymorphism. It would make sense to have them at the same place, as a 
"background topic" of a module. Moreover, placing the second part after 
"Lists and Tuples" would allow us to introduce polymorphic types and 
type variables with lists and tuples, which is probably more intuitive 
and easier for a newbie to grasp, and then expand a bit the concept with 
the other discussions.

* Sheer length. "Type Basics" currently weighs at 27k, and with the 
addition of the whole numerical types discussion it could easily get to 
the 40k range - which would certainly be very bad for readability. 
Having the number types discussion on a less crowded module would also 
give us more space to present very useful and practical things, such as 
the different division operators or functions like fromInt.

As usual, the only thing I can't find out is a good pair of names for 
the modules. In any case, since the division is slightly arbitrary 
perhaps we should simply stick to "Type Basics I" and "Type Basics II".

Regards,
Daniel Mlot

Re: Truth values and a couple other things

Heinrich Apfelmus — 2010-05-29T19:58:49

Sure, no problem. :) Eric Kow once remarked that the wikibook is a
"do-ocracy" which means that by doing something, like writing a chapter
or making a change, you automatically get the right to do it.


By the way, a principle that has helped me in my writing is that I try
to keep it really short, even minimize the number of words I use to make
a point. Great for clarity and readability, though a bit dry at times. I
always imagine that I'm writing for a reader whose attention is really
low and lasts only one additional paragraph, which is probably indeed
the case for any reader after a certain amount of time. :)


The GHC user's guide uses different colors: green for source listings
and red for GHCi examples (or the other way round).

The only reason I don't use <source> tags is because I'm too lazy to
type them out. :) The <code> tags are already too much for my taste.


Strictly speaking, there is no control flow in Haskell, so the term
"control structure" does not apply. I'd call it "case analysis" or
"definition by cases" instead.


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

Re: Cheat sheet

Heinrich Apfelmus — 2010-05-29T19:33:31

Ah, a bot performing the conversion automatically; that would indeed be
very useful.


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

Truth values and a couple other things

Daniel Mlot — 2010-05-29T08:09:44

While trying to think about how I could tackle the section on numerical 
types in "Type basics" I found out that I couldn't reason properly about 
it without knowing to which extent types would be discussed in the 
previous sections. That led me to "jump the gun" and attempt writing the 
bulk of the section myself. Apfelmus, please forgive me if that bothers 
you in any way (for instance, if you had a draft of your own being 
prepared) - in any case, just as I took some liberties with your outline 
feel free to do the same and turn my text upside down if you feel the 
need to :)

I will use this message to register some issues that are roaming in my 
mind lest I forget to mention them:

* Since we are reorganizing and rewriting most of the first chapters 
anyway it could be a good opportunity to standardize the style of code 
blocks. One option would be just using <source> tags everywhere to get 
syntax highlighting (with recent changes to the Wikibooks CSS files 
<source> is also bundled with the standard grey background box). There 
would be a couple possible issues to consider, though. We would probably 
have to do some template engineering, although I don't think that would 
be too troublesome. Another source of annoyance would be that GHCi 
printouts, ubiquitous on the early chapters, wouldn't be subject to the 
same standardization. Finally, there is the didactic concern of whether 
highlighting can be distracting for complete newbies during the first 
few modules (I do not have a really strong position on the subject but 
feel that "plain" plain text does have some charm due to sheer 
simplicity and transparency).

* One thing that occurred to me while writing about guards: is it even 
accurate to speak of our if/else and related constructs as "control 
structures"? Even if it is correct, is there any better term to use - 
one that does not have such imperative undertones?

Regards,
Daniel Mlot

Re: Cheat sheet

Daniel Mlot — 2010-05-27T19:13:38

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.


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_meta-edition

(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

Re: Cheat sheet

Heinrich Apfelmus — 2010-05-24T12:39:41

Feel free to ask on the #haskell IRC channel or the
beginners-HC+Z4NTRIlBAfugRpC6u6w< at >public.gmane.org mailing list for advice on your memory woes;
there's always someone around you can help.


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.


Sure, go ahead. :)


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

Re: Cheat sheet

Daniel Mlot — 2010-05-22T07:44:30

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:

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.


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

Cheat sheet

Heinrich Apfelmus — 2010-05-17T14:41:13


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

Re: More on topic reorganization

Heinrich Apfelmus — 2010-05-17T14:27:16

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.


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.


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

Re: Re: "List of topics" meta-module

Daniel Mlot — 2010-05-14T07:40:23

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 set up a mock-up cheat sheet at 
http://en.wikibooks.org/wiki/Haskell/Experimental_Modules/Cheat_sheet_prototype_1 
. 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

Re: "List of topics" meta-module

Heinrich Apfelmus — 2010-05-13T10:34:51

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

Re: Re: Splitting of "More on Datatypes"

Daniel Mlot — 2010-05-12T14:23:25

There is one very important issue which your proposal accounts for. As 
of now, that there no clear rationale which justifies the division 
between Basics, Elementary and Intermediate. For that reason, I don't 
believe the separation is really useful to readers. Furthermore, it is 
confusing to have "Elementary Haskell" as the second segment of the 
book, and a restructuring would be a nice opportunity to address such 
problems with less generic names.

As for the number of segments, I guess that as long as the underlying 
logic is clear it is just a convenience decision - for instance, if 
Haskell Basics ends up with, say, 15 modules it could be handy to make 
an arbitrary pt. 1 / pt. 2 division.

I will make an exercise and try to display an interpretation of your 
suggestions using the "List of topics" I created in the Wikibook. By the 
way: I guess that both "More about lists" and "List processing" would go 
in their entirety to the new "Basics" (except for the casual "teaser" 
about currying and partial function application nested in "More about 
lists")


That thread drives the point quite clearly, and I must admit I can, 
based on my newbie experiences, relate to this tendency of defining 
everything explicitly due to inexperience or merely to the desire of 
playing with the language. Guess that's why someone put a funny-looking 
"Don't get TOO excited about recursion" header in the "Recursion" module :-)


Full agreement here. A cheat sheet should really be a top priority, 
specially if there is nothing like what we are envisioning available 
elsewhere.

To your considerations on how the cheat sheet should be a 
"documentation" module detached from the main flow of the book, how it 
should restrict itself to the essentials and how it should be organized 
by topics I would only add a proposal on presentation. Essentially, I 
believe the "clutter" applies both ways - at the same time I don't want 
to be bothered by systematic discussion of Prelude while I'm trying to 
grasp the concepts I would like to be able to use the cheat sheet as 
expediently as possible, without having to wade through vague 
discussions or minute details if I don't want to, just picking the tool 
I need and stealing away back to the book or to my code. For that 
reason, a format like the one of "A Tour of the Haskell Prelude" is 
truly inadequate for what we intend. Instead, I believe the cheat sheet 
pages should have two parts:

* A very straight-to-the-point table, located at the very beginning of 
the pages, which presented the functions, type signatures and one-line 
descriptions, (ideally) in a way that no more than a quick glance should 
be needed for locating the function you need.

* Following the table, a section with more detailed comments on each of 
the functions. The subsections on each function would be linked from the 
table for convenience. This separation would also have the advantage of 
not forcing us to write the extra comments and notes in some strict 
format, as the necessary restrictions would already have been put in 
practice in the table.

I will help kickstarting the cheat sheet with formatting experiments and 
some initial examples, even if I don't think I can go too far on my own 
due to lack of Prelude experience.

Regards,

Daniel Mlot

Re: Splitting of "More on Datatypes"

Heinrich Apfelmus — 2010-05-12T08:53:29

Yes, exactly.

(Generic programming = doing things 'generically' for many data types,
like generalizing the  fold  function to every data type.)


True, the Beginner's track could lose one segment, but that's not
necessarily bad; the number of segments is not set in stone, after all.

That said, I envision a separation like this:

* Haskell Basics       => write any functionality
* Elementary Haskell   => write idiomatic Haskell code, full syntax
* Intermediate Haskell => write libraries, i.e. modules and type classes

So, Haskell Basics is really just a subset of what a full Haskell
programmer should know, but it's enough to write small programs in a
rather limited style that can nonetheless express pretty much anything.

For example, I imagine that Haskell Basics teaches only

   squares n = map square [1..n]
       where
       square x = x ^ 2

while a full Haskell programmer would write this as

   squares n = map (^2) [1..n]



There's nothing wrong with pattern matching. If anything, the problem is
this: With pattern matching and recursion, you can define any function
on lists. But then, it is also tempting to do exactly that and forgo the
vocabulary of functions offered in the Prelude, at the detriment of good
Haskell style.

For instance, consider the following task: you are given a file that has
a number on each line and you have to add them all up. A direct,
recursive, and utterly unintelligible solution would be to go character
by character and accumulate the sum

    example :: String -> Int
    example s = go 0 "" s
        where
        go sum 0      []     = sum
        go sum number (c:cs)
            | c == '\n'      = go (sum + read number) 0 cs
            | isDigit c      = go sum (number ++ [c]) cs

whereas the proper Haskell way to think about this task is

   example = sum . map read . lines

Okay, I created this example for this very purpose, but it does happen
in practice:

    "Memory usage problem"
    http://thread.gmane.org/gmane.comp.lang.haskell.beginners/3842
    (read the original question and my reply)


In the light of the above, conveying a good grasp on the vocabulary is
necessary, but I agree that a diligent study of standard libraries is
not necessarily a good idea. The thing is that the reader can only
memorize so many things at once, and it would be a waste to squander
this on uninteresting syntactic variations and library functions that he
doesn't need right now.

I imagine the best way to solve this is to present a subset of the
Prelude in style of a "cheat sheet", i.e. as documentation that the
reader should consult whenever he needs new vocabulary.

Astonishingly, such a thing does not exist yet, at least not how I
imagine it. There is

* Bernie Pope - A Tour of the Haskell Prelude
* GHC doc - Prelude

but the former has no thematic categories like the latter while the
latter does not restrict itself to the Haskell Basics subset. I've given
some private lessons recently and I was surprised to find that it's
really tricky to find the  show  function if you only know that you're
looking for something that will convert stuff into a  String .


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

"List of topics" meta-module

Daniel Mlot — 2010-05-12T00:25:33

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