Haskell/贡献者须知

There are a number of Haskell tutorials scattered around the web, along with a range of print books. But 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.

（上段大意：学习Haskell的方法很多。）

I have used all of these resources on the way to my current level of Haskell knowledge. It has often been a frustrating and difficult experience. I have started this Wikibook in the hope that it will continue to evolve and grow along with the language it describes so that at any time a Haskell programmer can easily find the next thing that they must learn, and then understand it fully. To this end I ask would-be contributors to 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. It is the task of any tutorial to split things up into digestible chunks. This may mean explaining or demonstrating things in a clumsier or less general way than you would like. So be it.
- （上段大意：用Haskell的方式思考。学习要细嚼慢咽。）

Do not treat the existing text or structure as sacrosanct. I make no claim to be a good teacher. If it would be better done another way then by all means do it. 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 more advanced topics, even if the main text has not caught up. In particular I would invite anyone who feels competent to tackle Concurrency, GADTs, Arrows, Parsing, User Interfaces, and FP Design Principles. Just make a note in the introduction about any pre-requisites that the main text does not yet cover.
- 有进取性，自学书本之外的内容。

What you can do （你能做什么）

Everyone that knows some Haskell should be able to contribute here. If you are...

（人人可以在此处贡献，如果你……）

New to Haskell, then please read through some of the first modules in the book. These will be crucial to you starting to understand the language, and 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 to one of the talk pages (best to do it to the talk page to of the contents page).
- 是初学者，试着学一下，如果学不会，那是作者们的错，请talk页面一下。
Still getting used to Haskell, you're in the process of learning the language. That means 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.
- 正试着习惯Haskell，那你对入门篇最有发言权。
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 plenty of new exercises (and answers too!), not to mention refactoring of the more advanced modules.
- 是Haskell的进阶者，那你应该能看懂以上的英语。
A veritable expert: there are many new modules you could start or propose. The Wikibook doesn't have any specific scope, but I think it'd be cool if could cover lots of the more advanced topics: there are no centralised tutorials in this area at the moment.
- 相当专家。写个新篇章吧。

Please, please, get involved! Chop and change as much as you want; the whole book's 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. It might be a good place to discuss ideas and directions.

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.