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 wi

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 wit

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 i

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 fin

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 shorte

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 te

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 (lik

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
"d

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 g

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 main

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 p

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 partia

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
t

"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