I have a very nitpicking question about the "standard module header" described here:
http://www.haskell.org/~simonmar/libraries/conventions.html
I am not sure if the header is intended to be automatically processed, so:
If the source file is a literate Haskell file, is the header supposed to be in the Haskell code portion of the file? Or, if the literate part is LaTeX, say, does one put it in a LaTeX comment so that it can appear at the head of the file?
Are literate files even allowed for "standard library 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