Idea to allow people to comment on Haskell docs

[Duncan Coutts]

On Mon, 2006-01-23 at 09:16 +0000, Simon Peyton-Jones wrote:
> | > Adding source code links would complete the picture.
> | 
> | Done!
> | 
> | Take a look at my example pages again:
> | http://haskell.org/gtk2hs/docs/devel/
> | http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
> |
> http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v
> :svgRender
> 
> Excellent stuff!  
> 
> I didn't follow all the details of your message, but I notice that the
> source code link doesn't move to the defn, presumably because there's no
> anchor in the source file.

Yeah, since I was linking to the raw darcs repo. But I wanted to show
off that it's possible to have URLs with anchors so I did it anyway. ;-)

> I guess that would require munging the source files to add the
> anchors?

Right, you'd want to link to a html version with anchors. There are
other tools that can do this. For example the Programatica project have
an html source code browser:

http://www.cse.ogi.edu/~hallgren/Programatica/tools/pfe.cgi
eg:
http://www.cse.ogi.edu/~hallgren/Programatica/tools/pfe.cgi?HsDeclPretty

One could generate their URL scheme using the slightly over-complex
substitution syntax I implemented:

--source=http://foo.bar/pfe.cgi%{MODULE|?%}%{KIND|#%}%{NAME}

> Unless one can link to "Foo.hs line 424", somehow.

I don't think that's possible.

> Suppose I follow the Comments link from (say) withSvgFromFile, and add
> some comments.  Will they automatically get the right anchor?

They will get the right anchor if people follow the convention of using
headings for each function they want to add notes about. In the wiki
markup that means writing:

= withSvgFromFile =

For a H1 style heading or

== withSvgFromFile ==
=== withSvgFromFile ===

etc for H2, H3 level headings.

> Because all the comments for SVG (rightly) end up in a single file,
> don't they?

Yes. (Though since the URL format is customisable the person setting up
the haddock docs can have it link in pretty much any way they like.)

> This looks great.  (Don't forget the documentation for Haddock itself.
> Documenting the feature makes it much more likely that people will use
> it.)

Yes, I've been writing stuff for that too.

Duncan