Super Haddock (was Re: Literate Programming)

[Simon Marlow]

=20
> This seems like a good way of transitioning from .lhs to=20
> haddock'd .hs.  In=20
> the long run, I think we (meaning Simon :-) should to extend=20
> haddock to=20
> take the place of the .lhs style of documenting code.

To generate .hs from .lhs, the right way is to use GHC:

  $ ghc -E Foo.lhs -o Foo.hs

The great thing about this is that it goes through the same
preprocessing stages that your source goes through in order to compile
it.  So for example if you use CPP on your source too, just say 'ghc -E
-cpp' to get the preprocessed output.

> I use haddock to document interfaces for modules and it works=20
> wonderfully=20
> for that (and it would be even better if I could use haddock comments=20
> inside records and in between constructor arguments, hint, hint).
>=20
> But I find myself using it in comments within code=20
> (especially within local=20
> functions) too.  Perhaps a haddock that had two modes (one=20
> for interfaces,=20
> one for implementation) would work.  The interface mode would=20
> work as it=20
> does now.  The implementation mode would produce a .html=20
> version of the=20
> entire module, using haddock comments to mark it up.
>=20
> Simon: how much work would this be?

That's an interesting idea.  It's not at all what Haddock was intended
for, but that's not to say it couldn't be done!

There are some issues to do with how you want the output to look: should
it retain the indentation of the original source, or ident according to
some fixed style?  If you want the indentation from the original source
then Haddock's front end will need some changes to support retaining
that information.  Throwing away the original indentation and generating
output indented according to a fixed style would be rather easier.

Cheers,
	Simon