[Haskell wikibook] "List of topics" meta-module

[Daniel Mlot]

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

[Heinrich Apfelmus]

Post by Daniel Mlot
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

[Daniel Mlot]

Post by Heinrich Apfelmus
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.)

Post by Heinrich Apfelmus
I'm still a bit hazy on the cheat sheet chapter, because it needs to do
* 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_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

[Heinrich Apfelmus]

Post by Daniel Mlot

Post by Heinrich Apfelmus
I'm still a bit hazy on the cheat sheet chapter, because it needs to do
* 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_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.
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

[Daniel Mlot]

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...

Post by Heinrich Apfelmus
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.

Post by Heinrich Apfelmus
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

[Heinrich Apfelmus]

Post by Daniel Mlot
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
***@haskell.org mailing list for advice on your memory woes;
there's always someone around you can help.

Post by Daniel Mlot

Post by Heinrich Apfelmus
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.

Post by Daniel Mlot
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

[Daniel Mlot]

Post by Heinrich Apfelmus

Post by Daniel Mlot
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
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.

Post by Heinrich Apfelmus
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_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

[Heinrich Apfelmus]

Post by Daniel Mlot

Post by Heinrich Apfelmus
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.

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.)

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


Regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

[Daniel Mlot]

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 :)

[Heinrich Apfelmus]

Post by Daniel Mlot
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.

Post by Daniel Mlot
(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.

Post by Daniel Mlot
* 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