Idea to allow people to comment on Haskell docs

[Duncan Coutts]

On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
> | I've had a go at patching Haddock to put a link on the page for each
> | module. It's controlled by an optional --wiki=URL flag.
> | 
> | As an example, I used this with the (devel version of the) Gtk2Hs
> docs:
> | 
> | http://haskell.org/gtk2hs/docs/devel/
> | 
> | For example this page:
> | 
> | http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
> 
> It looks great!  But I'd never have found the link if you hadn't pointed
> me at it.
> 
> Rather than "Wiki" say "User comments".  

Yes, that is better.

> And I think the per-entry [User comment] link is essential.  Typically
> people are going to be looking at a particular thing.  For example, here
> 	
> http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v
> %3AsvgRenderFromString
> is where I'd look for the link for svgRenderFromString.

Ok, I'll try that next. Where do you think that link should go within
each entry?

> Does MediaWiki support anchors in the middle of a page?  That's
> essential here -- we want one Wiki page for one Haddock page.

Yes. Each header automatically adds an anchor of the same name.

For example look at the definition page:
http://haskell.org/haskellwiki/Definition

There's a section with this markup:

== Historic development of Haskell ==

Which produces this anchor:
http://haskell.org/haskellwiki/Definition#Historic_development_of_Haskell


> On a closely related matter, Benjamin Pierce told me how often he wished
> that there was a link from the Haddock documentation to the source code
> for a function.  Especially for Prelude functions, he's dead right.  So
> another really useful Haddock enhancement would be the ability to add
> links to the source code from the Haddock docs --- again on a
> per-function basis.  Do you feel like adding that too?   Where should
> the code live?  I'd suggest snap-shoting it at the moment that the
> Haddock docs are generated, and putting the files with the Haddock docs.

I was thinking about that. It'd probably be a less difficult change to
haddock to get it to link to the source code, rather than picking it up
as it parses it.

Haddock does know the file name of each .hs file since it's invoked with
then on the command line. We can assume that the --source=URL points to
the location where haddock was invoked from. This gives us the full url
of each .hs file (I think). Then to deal with the use of pre-processors
etc, haddock should pickup the {-# LINE ... #-} pragmas just like ghc
does, so that it can discover the original file name.

Duncan