Standard module header trivia

[Simon Marlow]

> I have a very nitpicking question about the "standard module=20
> header" described
> here:
>=20
>   http://www.haskell.org/~simonmar/libraries/conventions.html
>=20
> I am not sure if the header is intended to be automatically=20
> processed, so:
>=20
> If the source file is a literate Haskell file, is the header=20
> supposed to be in
> the Haskell code portion of the file? Or, if the literate=20
> part is LaTeX, say,
> does one put it in a LaTeX comment so that it can appear at=20
> the head of the file?
>=20
> Are literate files even allowed for "standard library=20
> modules"? (I don't see
> any in the Hugs libraries distribution, for example.)

I'm personally not very fond of the literate style, so that's why none
of the existing hierarchical libraries are literate (I actually
converted several of them from .lhs into .hs).  One reason is that
Haddock doesn't understand literate scripts - or at least, it expects
all the documentation to be in comments in the Haskell source, which
leaves little reason to use literate comments.

To answer your question, the header is automatically processed by
Haddock to generate parts of the documentation.  Actually the document
you point to is slightly out of date, because the header should begin
with '-- |' (see the actual sources for examples).

On the other hand, we're certainly not going to ban .lhs files from
fptools/libraries.  Feel free to cook up some "guidelines for using
literate style in the libraries" and I'll add it to the document.

Cheers,
	Simon