On Tue, 2007-11-20 at 12:33 +0000, Krzysztof Kościuszkiewicz wrote:
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.
I'm pretty sure Brian O'Sullivan has written a Haskell implementation of this for the Real World Haskell book. I guess, they will publish the source once the book is out. Maybe the RWH guys can give some feedback on how this works, they seem to have very similar goals. / Thomas