Idea to allow people to comment on Haskell docs

[Duncan Coutts]

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:svgRender

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