Super Haddock (was Re: Literate Programming)

[Andy Moran]

[ Simon moved the thread to cafe, but I note there is still some activity i=
n=20
the main list, hence the crosspost. ]

On Friday 25 April 2003 02:34 am, Simon Marlow wrote:
> Ketil Z. Malde writes:
> > "Simon Marlow" <simonmar@microsoft.com> writes:
> > > Somebody else=B9 wrote:
> > >> This seems like a good way of transitioning from .lhs to
> > >> haddock'd .hs.  In the long run, I think we (meaning Simon :-)
> > >> should to extend haddock to take the place of the .lhs style of
> > >> documenting code.
> > >
> > > 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!
> >
> > I'm not sure I would like this.  I guess I'm one of (the apparently
> > very few?) who are using LaTeX lhs style (using \begin/\end{code}).
> > Would a Haddock replacement give me the same kind of functionality in
> > producing a nice printable copy?  I definitely have grown attached to
> > having math, footnotes, page headings, sections, and so on.
>
> Haddock isn't (intended to be) a literate programming system, so I don't
> imagine it will replace full LaTeX literate source any time soon.  The
> suggestion is just that it could produce nicely-formatted source code
> complete with lightly marked-up comments - which I think is a fine idea,
> and not too difficult to implement using the existing framework.

I just want to back Simon up here.  My original post was intended to=20
motivate a lightweight alternative to LaTeX lhs style, _not_ a replacement.
I'm delighted that there are people that use literate Haskell.  I don't:=20
it's too unwieldy for my purposes.

When documenting code for a small team of developers, when that code is=20
fluid, and must be maintained, having professional, very attractive,=20
browsable source code documentation is a wonderful thing.  When you can=20
produce that documentation with such minimal mark-up, it's going to get=20
used.=20

Cheers,

Andy

=2D-=20
Andy Moran                                              Ph.  (503) 526 3472
Galois Connections Inc.                                 Fax. (503) 350 0833
3875 SW Hall Blvd.                                    http://www.galois.com
Beaverton, OR 97005                                        moran@galois.com