On Fri, 2006-01-20 at 08:53 +0000, Simon Peyton-Jones wrote:
I think it looks great! Just the job, thank you.
Did you modify the Haddock documentation too?
I'll send patches for that too.
One thing to think about is what happens as the code evolves. When you re-generate the Haddock docs, what happens? Since the links are done by name (I think) it's probably not bad: you get links to the existing wiki entries so long as the name of the function doesn't change. If a function is deleted, I guess there'll be an orphan wiki entry, but that's probably ok. Worth documenting this in the Haddock docs.
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:svg... I've now got source and wiki links on the contest & index pages, at the top level of each module and for each exported item. (Some of the source code links are not accurate yet because the c2hs preprocessor has not yet been extended to preserve the original file name in its line pragmas, and many files in gtk2hs are .chs.pp files.) So yeah, I've got a patch to do all this stuff with haddock. I've extended the parser's source location tracking to include the original file name and then made haddocks lexer recognise C and Haskell style line pragmas and update the source code location and file name appropriately. Then we can get the original name of the file that defines each exported entity because the AST for each entity is tagged with its source location. So not only does this give us the accurate original file name for each module (which means the top level source code link will be right) but it also gives us the original file name for each export (which is not necessarily the same of course because of modules re-exporting things). So I've added source links for each item along with the wiki link for each item. So for linking to the raw source code one might use: --source=http://darcs.haskell.org/foo/%F (The %F expands to the original file name) If the source code is an html version with anchors for each name then we can link directly to each definition using: --source=http://darcs/haskell.org/foo/%M.html#%N (the %M expands to the module name with '.' replaced by '/' and the %N expands to the entity name) That's basically it. The rest of this email explains in rather too much detail how I've extended this URL variable expansion syntax to cope with a couple of practical issues. -------------------- In both the --wiki=URL and --source=URL options, the URL can contain these % wildcards. In the current haddock version they mean: %F the path & name of the .hs file %M the module mane with '.' changed for '/' My current patch changes and extends this: %F the path & name of the *original* source file (eg .lhs or .hs.pp) %M (same as before) %N the name of the documented function In addition there is some extended syntax to deal with the fact the URL serves three purposes, a top level source code link, a per module link and the per-export link. So what happens to the top level or per-module link if you use something like: --source=http://haskell.org/foo/doc.php?module=%M&name=%N is that for the per-module and top level link you get a url like: http://haskell.org/foo/doc.php?module=MyModule&name= http://haskell.org/foo/doc.php?module=&name= or in the wiki example: --source=http://haskell.org/haskellwiki/Gtk2Hs/%M#%N http://haskell.org/haskellwiki/Gtk2Hs/Graphics.UI.Gtk# http://haskell.org/haskellwiki/Gtk2Hs/# This is slightly more than a cosmetic niggle. In the wiki example http://haskell.org/haskellwiki/Gtk2Hs and http://haskell.org/haskellwiki/Gtk2Hs/ are two different pages. What we want is for some parts of the URL syntax to disappear when the context is not appropriate. We want theses URLs for the top level, per-module and per-item cases: http://haskell.org/haskellwiki/Gtk2Hs http://haskell.org/haskellwiki/Gtk2Hs/Graphics.UI.Gtk http://haskell.org/haskellwiki/Gtk2Hs/Graphics.UI.Gtk#foo So I've implemented this extended syntax: --source=http://haskell.org/haskellwiki/Gtk2Hs%{MODULE|/%}%{NAME|#%} %{MODULE|/%} expands to: /Graphics.UI.Gtk when there is a module and expands to nothing when there is not. Similarly, %{NAME|#%} expands: #foo when there is a export name and expands to nothing when there is not. So the syntax is: %{VAR|string using the % char} Which expands to nothing if the var is nothing and otherwise expands to the insertion string with % replaced by the value of the var. So another example is: --source=http://haskell.org/blah/doc.php%{MODULE|?mod=%}%{NAME|&name=%} Which would give us URLs like: http://haskell.org/blah/doc.php http://haskell.org/blah/doc.php?mod=Foo.Bar http://haskell.org/blah/doc.php?mod=Foo.Bar&name=foo The other thing that people want to customise is how the module name translates into the url, the current code assumes everyone wants to convert '.'s to '/'s but I imagine this will not be universal. In my previous demo of wiki links I wanted to keep the '.' characters. So as an additional extension I allow %{MODULE/./c} where 'c' is the replacement character. So the common ones would be: %{MODULE} %{MODULE/.//} %{MODULE/./-} To give: Graphics.UI.Gtk Graphics/UI/Gtk Graphics-UI-Gtk And if people really want the two syntaxes can be combined: %{MODULE/./-|(%)} which gives: (Graphics-UI-Gtk) As a concrete example, here's the command I used to generate the Gtk2Hs docs: haddock --html --odir=docs/reference --title="Gtk2Hs" --dump-interface=docs/reference/gtk2hs.haddock --prologue=docs/prologue.txt --wiki=http://haskell.org/haskellwiki/Gtk2Hs%{MODULE|/%}%{NAME|#%} --source=http://darcs.haskell.org/gtk2hs/%{FILE}%{NAME|#%} --read-interface=http://haskell.org/ghc/docs/latest/html/libraries/base,docs/base.haddock glib/System/Glib/FFI.hs glib/System/Glib/UTFString.hs (... etc) Phew! Duncan