[Haskell-cafe] Re: expanded standard lib

[apfelmus]

Simon Peyton-Jones wrote:
> | > 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.

What technology to use, that's the *key* question. If we forget 
everything what we currently can do with a computer and instead imagine 
what we could do, the answer would probably be:

The documentation / source code can be edited directly while viewing it 
(i.e. Wiki + WYSIWYG). Moreover, it's possible to attach lots of 
Post-It® notes to sections / paragraphs / sentences with scribbled 
comments / questions / remarks about content / administrative tasks. 
Those notes can be hidden to get a clean view. A wiki is rather 
centralized, so a form of decentralization / version control à la darcs 
is needed, at least for some parts like the source code. Last but not 
least, there's a tension between quality and "editable by everyone", so 
some form of access control is mandatory and further means to ensure 
quality are needed, that's the hard part.

The above ideal is entirely realizable, just not with existing 
technology like web-browsers / text editors . For instance, it's 
desirable to be able to edit source / haddock with a text editor like 
right now. But one would also like to edit it right in the (generalized) 
web-browser. Ideally, one could just pipe the underlying document 
through a lens

   data Lens s a = Lens { get :: s -> a; set :: a -> (s -> s); }

   text    :: Lens HaskellDocument ASCII
   browser :: Lens HaskellDocument Html

so that the edits in the view are reflected in the document. (Same for 
IDEs or GUIs or whatever).


Regards,
apfelmus