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.