Hello I did a little digging on this issue and didn't find a definitive answer. According to the Haddock page in the wiki, Haddock is the de facto way of documenting files [http://haskell.org/haskellwiki/Haddock]. Does this mean that literate source files should be discouraged? They seem to be fairly common, especially in conjunction with Cabal (i.e., Setup.lhs). They also appear in quite a few beginner tutorials, which can send new users down the wrong path (e.g., http://haskell.org/haskellwiki/How_to_write_a_Haskell_program). Is there an effort and/or intent to move the GHC sources away from .lhs entirely? --- The reason I ask is: I'm looking at the Test.HUnit modules and there are no Haddock annotations. I thought I'd help document the modules but, when I had a look at the source files, I found they were .lhs instead of .hs. There is already some documentation in the files but it's not visible to Haddock. What's the best way to proceed in a case like this? 1. Shoe-horn in the Haddock annotations by putting them in the code sections (e.g., > -- | Document comment...) but this seems a little cumbersome, especially if these comments show up in the published form of the .lhs file. 2. Rename to the files to .hs and touch up the files so they compile, then add the Haddock annotations. 3. Another option? --- I get the feeling that HUnit isn't getting much attention. Is that because it's "done" or because it's obsolete and will soon be removed? Thanks, Richard G.
On Sat, 2008-06-14 at 22:20 -0600, Richard Giraud wrote:
I'm looking at the Test.HUnit modules and there are no Haddock annotations. I thought I'd help document the modules but, when I had a look at the source files, I found they were .lhs instead of .hs. There is already some documentation in the files but it's not visible to Haddock.
What's the best way to proceed in a case like this? 1. Shoe-horn in the Haddock annotations by putting them in the code sections (e.g., > -- | Document comment...) but this seems a little cumbersome, especially if these comments show up in the published form of the .lhs file.
2. Rename to the files to .hs and touch up the files so they compile, then add the Haddock annotations.
3. Another option?
You can use: | blah blah
ordinary code
And if you're using Cabal then it uses an extended 'unlit' function which generates sensible input for haddock. In fact this only works at the moment with haddock-0.x (ie 0.8, 0.9) because haddock-2.x does it's own unliting. For an example of this lhs/haddock style, see takusen. Duncan
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Does this mean that literate source files should be discouraged? They seem to be fairly common, especially in conjunction with Cabal (i.e., Setup.lhs).
I think the reason for having Setup.lhs instead of Setup.hs is that you can put #!/usr/local/bin/runhaskell in their first line. Then chmod +x Setup.lhs and you can do ./Setup.lhs configure etc. So, this has nothing to do with literate programming. Best regards, J.W. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.4-svn0 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFIVfxBDqiTJ5Q4dm8RAtZkAJ4r0qWQiUmQvsPhJMAFiccMvmJTQgCcCSH9 Y3Wph09j9/j2yJ2bsYYMXfQ= =NIax -----END PGP SIGNATURE-----
On Mon, 2008-06-16 at 07:38 +0200, Johannes Waldmann wrote:
Does this mean that literate source files should be discouraged? They seem to be fairly common, especially in conjunction with Cabal (i.e., Setup.lhs).
I think the reason for having Setup.lhs instead of Setup.hs is that you can put #!/usr/local/bin/runhaskell in their first line. Then chmod +x Setup.lhs and you can do ./Setup.lhs configure etc. So, this has nothing to do with literate programming.
And it's really more trouble than it's worth, IMHO. runghc Setup is the better recommendation I think because it works for .hs or .lhs and it works on operating systems with no concept of #! or chmod. So with that the recommendation then the simplest possible Setup script is: Setup.hs: import Distribution.Simple main = defaultMain Duncan
I never thought about that. I've been using Setup.hs with "#!/usr/bin/env runhaskell" and never had any problems. I guess the only thing that would be gained by using Setup.lhs is the ability to compile the setup program. Is that something that's commonly done? Richard G. Johannes Waldmann wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Does this mean that literate source files should be discouraged? They seem to be fairly common, especially in conjunction with Cabal (i.e., Setup.lhs).
I think the reason for having Setup.lhs instead of Setup.hs is that you can put #!/usr/local/bin/runhaskell in their first line. Then chmod +x Setup.lhs and you can do ./Setup.lhs configure etc. So, this has nothing to do with literate programming.
Best regards, J.W.
-----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.4-svn0 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFIVfxBDqiTJ5Q4dm8RAtZkAJ4r0qWQiUmQvsPhJMAFiccMvmJTQgCcCSH9 Y3Wph09j9/j2yJ2bsYYMXfQ= =NIax -----END PGP SIGNATURE-----
I never thought about that. I've been using Setup.hs with "#!/usr/bin/env runhaskell" and never had any problems.
I guess the only thing that would be gained by using Setup.lhs is the ability to compile the setup program. Is that something that's commonly done?
That's what I do. My normal install procedure is: ghc --make setup setup configure setup build setup install If only takes a couple of seconds for ghc to compile setup, and then it runs instantly. If I was to use runghc then it would recompile (in ghci) for each invocation. I use #! in Setup.hs (non-lit) and it compiles fine, so no worries there either. Alistair
On Mon, 2008-06-16 at 15:39 +0100, Alistair Bayley wrote:
I never thought about that. I've been using Setup.hs with "#!/usr/bin/env runhaskell" and never had any problems.
I guess the only thing that would be gained by using Setup.lhs is the ability to compile the setup program. Is that something that's commonly done?
That's what I do. My normal install procedure is: ghc --make setup setup configure setup build setup install
Though of course these days we can just: cabal install It compiles Setup.(l)hs if necessary or for build types other than Custom it can just do it directly without going via the Setup script. Duncan
participants (4)
-
Alistair Bayley -
Duncan Coutts -
Johannes Waldmann -
Richard Giraud