Haskell/Notes for contributors

Along with a range of print books, there are a number of Haskell tutorials scattered around the web. None of these can provide a one-stop-shop for the student of Haskell. The print books mostly describe Haskell 98, but since then many of the "extensions" introduced by GHC have since become de facto standards. In addition, the theory and practice of monads has expanded greatly and arrows are starting to become used in mainstream libraries. Hence, the neophyte Haskeller is faced with a collection of disorganised resources, including textbooks, academic papers written by and for experts, isolated tutorials and explanations on Wiki pages, and, of course, willing helpers on mailing lists, IRC channels, and forums.

Making the most of all the resources can be a frustrating and difficult experience. Ideally, this Wikibook will continue to evolve and grow along with the language. We want a definitive reference where Haskell programmers can easily find the next thing that they must learn and then learn to understand it fully and clearly. To this end, contributors should observe the following:

• Ensure that you only use a language construct or concept after it has been explained. This can be difficult: Haskell contains many sophisticated concepts in a tight-knit whole with each supporting the others. Nevertheless, it is impossible to learn a language by swallowing the whole thing at once. A good tutorial splits things up into digestible chunks. Sometimes, explaining or demonstrating things in a clumsier or less general way than you would like helps keep things accessible.

• Do not treat the existing text or structure as sacrosanct. If there is a place for improvement, then by all means go ahead and change things. Remember that Wikibooks are under version control, so any mistake can always be backed out. (Having said that, major changes should probably be discussed first).

• Feel free to run ahead with writing more advanced topics, even if the main text has not caught up. In particular, chapters on Concurrency, GADTs, Arrows, Parsing, User Interfaces, and FP Design Principles all need work. Just make a note in the introduction about any pre-requisites that the main text does not yet cover.

What you can do

Anyone who knows some Haskell should be able to contribute here. If you are...

• New to Haskell: Please read through some of the first modules in the book. These will be crucial to you starting to understand the language. If they're not clear enough, they need to be changed. If you can't understand them, or find they don't provide a wide enough knowledge base, add a complaint on one of the talk pages (best to do it to the talk page of the contents page).
• Still getting used to Haskell: You're in the perfect position to 'refactor' the beginners' modules in the Wikibook! You know best what's helpful to newcomers and what's just downright confusing. Be brave, delete large chunks of text if they're simply rubbish.
• Growing up with Haskell: There are plenty of tasks for you. The Wikibook needs better coverage of the Hierarchical modules (don't overlap with the Haddock docs too much, though) as well as new exercises (and answers too!). The advanced modules could use some refactoring.
• A veritable expert: There are many new modules you could start or propose. The Wikibook doesn't have a limited scope. It would be great to cover lots of the more advanced topics.

Please, please, get involved! Chop and change as much as you want. Again, the whole book is on version control, so no change is too drastic.

Getting in touch

Note that Wikibook contributors can sometimes be found in the #haskell channel on irc.freenode.net. That is a great place to discuss ideas and directions.

There is also a mailing list specific to the Haskell wikibook (and actually all Haskell educational materials). See http://www.haskell.org/pipermail/wikibook/

Below are some notes from past and current contributors about efficient editing of the Wikibook:

Using Emacs

FIXME: publish this somewhere more sensible

I love Emacs and can't stand using a text area to edit Wikibook pages in, especially long ones where I'm going to be writing a lot. After Firefox crashing on me once or twice and me losing several hours work, I realised there has to be a more sensible way of contributing to MediaWiki projects. This is what I've come up with:

wikipedia-mode.el

Firstly, wikipedia-mode is essential for font-locking. It's built on outline mode. It does, however, include a few stupid shortcuts, so here is how I have it installed:

(autoload 'wikipedia-mode "wikipedia.el"
 "Major mode for editing documents in Wikipedia markup." t)
(add-hook 'wikipedia-mode-hook 'flyspell-mode)
(add-to-list 'auto-mode-alist 
  '("\\.wiki\\'" . wikipedia-mode))
(defun unset-wikipedia-bindings ()
  (interactive)
  (local-unset-key (kbd "C-<up>"))
  (local-unset-key (kbd "C-<down>"))
  (local-unset-key (kbd "C-<left>"))
  (local-unset-key (kbd "C-<right>")))
(add-hook 'wikipedia-mode-hook 'unset-wikipedia-bindings)

MVS

Now we can edit MediaWiki files in Emacs, it'd be nice to post them back to the server without having to copy-paste into Firefox. A guy called Mark Jaroski wrote MVS, which is a client-side program for interacting with MediaWiki servers. Here's a typical session:

Specify login details for the wikibook, with the 'en' locale
mvs login -d wikibooks.org -u <username> -p <password> -l en
Pull the 'Haskell/Notes for contributors' module from the server
mvs update 'Haskell/Notes for contributors.wiki'
... hack away on that file ...
Commit the changes back to the server
mvs commit -m "New notes" 'Haskell/Notes for contributors.wiki'

There'll be a new version, 1.0, soonish, which should contain some new features making life a little easier. Here's an extract from an email conversation I've had with him indicating what'll be added:

Date: Thu, 20 Jul 2006 09:50:06 +0200
From: Mark <mark@geekhive.net>
To: David House <dmhouse@gmail.com>
Subject: Re: MVS comments and requests

David House wrote:
> I've been using MVS for a while now, moving my Wikibooks editing over
> to Emacs, which has been very handy. As Emacsers are never productive
> enough, I decided to try and hack together some Emacs lisp to
> integrate Emacs and MVS a bit further. The end result will basically
> be the ability to do C-x v v (that's Emacs-speak for Ctrl+x, then v,
> then v), type a message, C-c C-c and have the page sent to the server.
> Or, C-c C-p whilst I'm still typing and I get a preview automatically
> displayed in Firefox.

That's very cool.  I have a similar vim module.

> Firstly, the restriction that you have to issue commands from the
> 'working copy root', or whatever it's called, is a little...
> restrictive. :) Say if I download Foo/Bar, then cd to Foo, I should be
> able to update/commit/preview/etc Bar, with the relative paths
> resolved. Is this feasible?

Yes, but I think it's probably going to have to wait for the
next version or so.  I'm working on an major overhaul for
the 1.0 version, with more of an OO api.  This will make it
easier to add images and other neato things.

> Secondly, MVS is slow. I realise this is probably because WikiMedia's
> servers aren't the snappiest in the world, and most of the time, I'm
> willing to wait for update and commit commands, but preview is where
> it bites. I'd like the possibility to install MediaWiki locally, then
> have MVS fire off preview requests to the local, rather than remote,
> server. This would basically boil down to an option allowing you to
> have a separate recipient address for previews, AFAICT. 

That's also part of my little plan.  Of course you can
pretty much get this effect now just by having two
.mediawiki files and swapping them around when you want to
switch servers.

> I can think of two problems here: templates obviously
> wouldn't work, and namespaces might get a little funky.
> However I'm willing to live with both of these for a
> faster preview. In the future, perhaps you could also
> implement something to download all the templates linked
> to from a page, perhaps even automatically.

I agree.

VC bindings

Not implemented yet, but in the Big Plan, is to write some VC bindings for Emacs, so committing should be as easy as C-x v v. However, I'm going to wait until some of the aforementioned features are implemented. At the moment, my design for key bindings will be something like:

C-x v v, C-c C-f

Commit file to the server.

C-c C-m

Commit minor version to the server

C-c C-p

Preview the file.

In addition to the VC bindings.

Fast preview

Most of MVS is slow, but that's okay, because MediaWiki is slow. However, previewing is one area where things could be improved. My plan is to install a local MediaWiki, then have an option in MVS to send preview requests to that server instead of to the remote one, speeding things up. As Mark points out, this is available currently by swapping the .mediawiki files over.

If you've got any ideas, tack them up here.

Using your favourite text editor

Most of the hints above can be adapted to other text editors. See Text editor support on Wikipedia for details.

Formatting tips

• A very common problem involves text on the first few lines of a page overlapping with the chapter table of contents in the right side. To fix that, place {{clear}} at the very beginning of the page, just above the chapter TOC.
• A related problem sometimes affects the navigation boxes at the bottom of the page, which can get squeezed to a very narrow width when there are other box templates just above them. Separating the boxes with {{-}} fixes the problem.