[Haskell-cafe] expanded standard lib

[Simon Peyton-Jones]

| > the php documentation has "user contributed notes" where people can leave
| > sniplets of useful code as comments, eg
|
| > http://www.php.net/manual/en/introduction.php
|
| > I think this is a very nice feature.
|
| I would love to have this on haskell, especially because the
| documentation often lack example(s)

We've discussed this a couple of times at GHC HQ, at least in relation to GHC's user manual and library documentation.  It's a *great* idea, because it allows everyone to improve the documentation.

But we're just not sure how to do it:

* What technology to use?

* Matching up the note-adding technology with the existing infrastructure
- GHC's user manual starts as XML and is generated into HTML by DocBook
- In contrast, the library documentation is generated by Haddock.

* Hardest of all: evolution.  Both GHC's user manual and library docs change every release.  Even material that doesn't change can get moved (e.g. section reorganisation).  We don't want to simply discard all user notes!  But it's hard to know how to keep them attached; after all they may no longer even be relevant.  They almost certainly don't belong in the source-code control system.


If someone out there knows solutions to these challenges, and would like to help implement them, we'd love to hear from you.  Accurate documentation, with rich cross-links (e.g. to source code), and opportunities for the community to elaborate it, is a real challenge for a language the size of Haskell and its libraries.

Simon