[Haskell-cafe] expanded standard lib

[Krzysztof Kościuszkiewicz]

On Tue, Nov 20, 2007 at 08:55:47AM +0000, Simon Peyton-Jones wrote:

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

I would advocate using a comment system that is similar to the one
at http://djangobook.com/. In terms of user manual comments might be
attached to sections and paragraphs in the document. Haddock already
generates HTML anchors for every type, variable and class, so these are
good candidates to attach user comments to.

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

Comments in both html user guide and library docs could be easily
cross-referenced to specific parts of docbook/haskell source. The
remaining part (and I admit, labour intensive) would be to take the
notes into consideration while updating the documentation for the next
release. This doesn't happen too often (once a year? but if I'm wrong
please tell me) and I guess the whole point of accepting user's comments
is to improve the dock - that is to let writers address the issues in
the next version.

Now, examples illustrating use of library functions - that's a different
story...

Regards,
-- 
Krzysztof Kościuszkiewicz
Skype: dr.vee,  Gadu: 111851,  Jabber: kokr at jabberpl.org
"Simplicity is the ultimate sophistication" -- Leonardo da Vinci