[Haskell-cafe] Re: Haddock API and .haddock interface files questions
2010/10/26 Claus Reinke claus.rei...@talk21.com: Some questions about Haddock usage: 1. Haddock executable and library are a single hackage package, but GHC seems to include only the former (haddock does not even appear as a hidden package anymore). Is that intended? Yes, I think that's so that GHC maintainers don't need to worry about API changes in Haddock when making new releases. The Haddock API is not very stable. 2. Naively, I'd expect Haddock processing to involve three stages: 1. extract information for each file/package 2. mix and match information batches for crosslinking 3. generate output for each file/package I would then expect .haddock interface files to repesent the complete per-package information extracted in step 1, so that packages with source can be used interchangeably with packages with .haddock files. However, I can't seem to use 'haddock --hoogle', say, with only .haddock interface files as input (No input file(s).). Haddock currently mostly works on GHC's front-end AST, called HsSyn, which is not stored in the .haddock files, so that's why you need sources. I say mostly, because the one-year old feature that we call cross-package documentation (allowing the user to re-export documentation from other packages), is implemented by taking information from GHC's .hi files, converting that to HsSyn. The syntax used in the .hi files is slightly less detailed than HsSyn so we loose some information about the exact declaration syntax used by the programmer (brackets in type expressions, infix/prefix declaration styles, etc - nothing that is semantically relevant). In theory we could continue along that road and let you build output from a combination of .haddock and .hi files. Or we could do as you say and just put everything in the .haddock files (in which case we could use the HsSyn type). 3. It would be nice if the Haddock executable was just a thin wrapper over the Haddock API, if only to test that the API exposes sufficient functionality for implementing everything Haddock can do. Yes, good idea. We haven't done that yet since the API started out as something quite experimental, and it's still in that stage although it has gained a lot more functionality recently. Instead, there is an awful lot of useful code in Haddock's Main.hs, which is not available via the API. So when coding against the API, for instance, to extract information from .haddock files, one has to copy much of that code. Also, some inportant functionality isn't exported (e.g., the standard form of constructing URLs), so it has to be copied and kept in synch with the in-Haddock version of the code. Right. We should export that. It might also be useful to think about the representation of the output of stage 2 above: currently, Haddock directly generates indices in XHtml form, even though much of the index computation should be shareable accross backends. That is, current backends seem to do both stage 2 and stage 3, with little reuse of code for stage 2. True. The index could be factored out of the Xhtml backend and added to the output of stage 2. It seems that exposing sufficient information in the API, and allowing .haddock interface files as first-class inputs, there should be less need for hardcoding external tools into Haddock (such as --hoogle, or haddock-leksah). Instead, clients should be able to code alternative backends separately, using Haddock to extract information from sources into .haddock files, and the API for processing those .haddock files. Are these expectations reasonable, or am I misreading the intent behind API and .haddock files? Is there any documentation about the role and usage of these two Haddock features, as well as the plans for their development? No documentation yet, but yes, the long term plan is to be able to split Haddock in parts: one program that creates data from sources, probably resulting in a .haddock file or maybe something text based, and backends that use those files. The API should provide a convenient way to read the files. It's not been fleshed out in detail yet, and the API is quite ad-hoc at the moment so we need think more about this and write documentation on the Haddock trac. Thanks for the input! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: patch to generate single-index page in addition to perl-letter indexes indices.
2010/10/24 Ryan Newton new...@mit.edu: When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in Window in the Chart package -- no luck: http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index.html Therefore I propose that even when generating the A-Z individual pages that there also be an All option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/ right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock: http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly! Patch applied. Thanks! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? Now imagine something like instance Show Secret (inside the Ex module). The user of the module then can write show foo, and so it should be documented? J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On 28 August 2010 21:33, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? The more important question is why doesn't it have a type signature? :p How does GHC deal with that kind of situation? Off the top of my head, I would think that in terms of how you could use it, that would be equivalent to also exporting Secret (the type, not the constructor); i.e. module Ex (Secret, foo) where -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
in terms of how you could use it, that would
be equivalent to also exporting Secret [...]
well, expect that you cannot use the type's name in signatures,
so you'd have to rely on type inference.
Out of curiosity I just checked javadoc's behaviour on
public class Ex {
public interface Show { }
static private class Secret implements Show { }
public Secret foo () { return new Secret (); }
static public class Known implements Show { }
public Known bar () { return new Known (); }
}
and it does generate documentation for all the public identifiers,
with a non-linked result type for foo,
and it does not list Secret among the known instances for Show.
Well, then I checked haddock (2.7.2) for
module Ex ( foo, bar, Known ) where
data Secret = Secret
foo = Secret
instance Show Secret
data Known = Known
bar = Known
instance Show Known
and it behaves identically (does not mention Secret as a known instance).
So, is this the behaviour that the original poster wanted?
J.W.c
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On Sat, Aug 28, 2010 at 1:41 PM, Ivan Lazar Miljenovic ivan.miljeno...@gmail.com wrote: On 28 August 2010 21:33, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? The more important question is why doesn't it have a type signature? :p How does GHC deal with that kind of situation? Off the top of my head, I would think that in terms of how you could use it, that would be equivalent to also exporting Secret (the type, not the constructor); i.e. module Ex (Secret, foo) where I tried this once, because I was wondering the same thing. Basically it works the way I expected: if you export functions which have a given type in their signature, but the type is not exported, you can use the functions and combine them however you want, but you can't explicitly mention or use the unexported type anywhere. At the time I actually had a use case in mind for why this would be useful, but I can't remember what it was. -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Work is punishment for failing to procrastinate effectively. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
Perhaps Haddock could exclude class instance reporting [...] Instances are global, and cannot be hidden. You cannot prevent their use, so you might as well document them. Otherwise you'll have users complaining when they assume the instance isn't there, and write their own, and then see the error message, but don't find the explanation in the documentation. (rant follows) Yes, globality is bad. - One could wish for (e.g.) let foo :: [Foo] = sort bar where instance Ord Foo where ... Of course this is not Haskell, and that's why there is sortBy etc, where the extra argument corresponds to the dictionary of the type class. Presumably this could be hidden as an implicit parameter, so I guess local instances could be made to work. And local types as well? Sometimes I want them. Heretically speaking, since Java has this (local types), 1. there must be a reason, and 2. there is a way to implement it (well, at least something like it). J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On 25 August 2010 21:36, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting [...] Instances are global, and cannot be hidden. You cannot prevent their use, so you might as well document them. Yes you can; in that example Alexander linked to before, you can't use the class methods of GraphvizResult; try it, they are: outputCall :: (GraphvizResult o) = o - String isBinary :: (GraphvizResult o) = o - Bool In this case, the class is one defined inside that module and used solely for those two data types; it isn't exported, and the only way you can tell it exists is that Haddock mentions the instances. -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
In this case, the class is one defined inside that module and used solely for those two data types; it isn't exported, and the only way you can tell it exists is that Haddock mentions the instances. OK. I was confused because the text of the posting mentioned MonadReader and MonadState (and their methods set/get/ask/...), which are globally known. J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problem
Does anyone have any suggestions or do I have to start building haddock myself? Ok I built it from source rather than using the Haskell Platform exe and it now works. Perhaps the packager of the Haskell Platform for Windows could take a look at why the binary is behaving as it does? Dominic. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problem
malcolm.wallace malcolm.wallace at me.com writes: I haven't been following closely, but how did you install haddock? From a binary dist? Is it possible that one of the Windows binary dists has a baked-in location for something on the E: drive, which existed on the packager's machine but not on the final installed machine? We are on the Haskell Platform 2010.1.0.0 and haddock comes as a .exe with it. Does anyone have any suggestions or do I have to start building haddock myself? Thanks, Dominic. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problem
David Waern david.waern at gmail.com writes: I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. Perhaps another line of attack would be to see why haddock thinks I have an E: drive? ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/15 Dominic Steinitz domi...@steinitz.org: David Waern david.waern at gmail.com writes: I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. Perhaps another line of attack would be to see why haddock thinks I have an E: drive? Right. However I suspect it's not a problem with Haddock but rather something to do with the platform. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/15 David Waern david.wa...@gmail.com: 2010/6/15 Dominic Steinitz domi...@steinitz.org: David Waern david.waern at gmail.com writes: I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. Perhaps another line of attack would be to see why haddock thinks I have an E: drive? Right. However I suspect it's not a problem with Haddock but rather something to do with the platform. Here's something similar: http://trac.haskell.org/haskell-platform/ticket/119 I tried myself on windows, and haddock --print-ghc-libdir yields: E:\ghc\ghc-6.12.1\lib and I don't have an E: either. So Haddock seems to be more or less broken on windows in the current platform. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problem
Try --optghc=-package-conf --optghc=file, to point Haddock at the custom DB. Hi David, Thanks for the quick response. No dice I am afraid. Dominic. BTW this (using optghc) used to work on previous versions of haddock (iirc 2.4 and 2.5). ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe --optghc=-package-conf --optghc=c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell _packages\fpf.package.conf backendc\PAD2C.hs haddock.exe: can't find a package database at E:\ghc\ghc-6.12.1 \lib\package.conf.d ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 Dominic Steinitz domi...@steinitz.org: Try --optghc=-package-conf --optghc=file, to point Haddock at the custom DB. Hi David, Thanks for the quick response. No dice I am afraid. Dominic. BTW this (using optghc) used to work on previous versions of haddock (iirc 2.4 and 2.5). ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe --optghc=-package-conf --optghc=c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell _packages\fpf.package.conf backendc\PAD2C.hs haddock.exe: can't find a package database at E:\ghc\ghc-6.12.1 \lib\package.conf.d OK, it seems like the path from the ghc-paths package overrided what you specified. I'm not sure this will work, but you could try: haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.package.conf David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 David Waern david.wa...@gmail.com: OK, it seems like the path from the ghc-paths package overrided what you specified. I'm not sure this will work, but you could try: haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.package.conf Sorry, that should be haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problem
David Waern david.waern at gmail.com writes: 2010/6/14 David Waern david.waern at gmail.com: OK, it seems like the path from the ghc-paths package overrided what you specified. I'm not sure this will work, but you could try: haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.pack age.conf Sorry, that should be haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages David Better but no cigar. ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.pack age.conf backendc\PAD2C.hs haddock.exe: can't find a package database at C:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.pack age.conf\package.conf.d And indeed I do not have a directory called package.conf.d. So I created one and copied our custom package databse into it but still no luck: ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages backendc\PAD2C.hs haddock: internal Haddock or GHC error: C:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\package. conf.d\package.cache: openBinaryFile: does not exist (No such file or directory) I'm not what this file is. Is it the same as the index file that cabal uses? Dominic. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 Dominic Steinitz domi...@steinitz.org: So I created one and copied our custom package databse into it but still no luck: ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages backendc\PAD2C.hs haddock: internal Haddock or GHC error: C:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\package. conf.d\package.cache: openBinaryFile: does not exist (No such file or directory) I'm not what this file is. Is it the same as the index file that cabal uses? I don't know exactly what that file is, but -B is actually for pointing Haddock at the GHC lib dir, so it's not surprising that it doesn't work. I thought that perhaps the package.conf.d file is the only thing it needs from that directory, but that doesn't seem to be the case. I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock installation weirdness?
This might be heavy handed but I think I just got over this by clobbering my .ghc directory and redoing cabal install haddock Dave On Thu, Feb 25, 2010 at 7:23 PM, David Leimbach leim...@gmail.com wrote: I'm on Mac OS X Snow Leopard, and can't get haddock installed due to the following error: Resolving dependencies... Configuring haddock-2.6.0... Warning: This package indirectly depends on multiple versions of the same package. This is highly likely to cause a compile failure. package haddock-2.6.0 requires Cabal-1.8.0.2 package ghc-6.12.1 requires Cabal-1.8.0.2 package bin-package-db-0.0.0.0 requires Cabal-1.8.0.2 Preprocessing library haddock-2.6.0... Preprocessing executables for haddock-2.6.0... unused terminals: 1 Building haddock-2.6.0... command line: cannot satisfy -package-id ghc-6.12.1-b691a185e99c62533666d9a28a9e1988: ghc-6.12.1-b691a185e99c62533666d9a28a9e1988 is unusable due to missing or recursive dependencies: Cabal-1.8.0.2-a08510b9460f1b65f9dee06ed53f0650 bin-package-db-0.0.0.0-0c559ebe951f9972c4e6dfe5ebd4ce6a (use -v for more information) cabal: Error: some packages failed to install: haddock-2.6.0 failed during the building phase. The exception was: ExitFailure 1 When I do a ghc-pkg list | grep Cabal I get the following: ghc-pkg list | grep Cabal Cabal-1.8.0.2 Cabal-1.8.0.2 I'm wondering if this means I have a copy in my .cabal, and another from GHC,and if that could be causing a problem? I'm trying to work on the Haddock docs for the NineP package I uploaded the other day, and would rather not have to finish uploading before previewing the result :-) Dave ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Failed to create dependency graph (when adding sections with * or a module heading)
Simple fix (terrible error message): Move the ( up to the line with the module name. Previous bad code: module Data.DualMap -- * The @DualMap@ abstract type ( DualMap () -- * (?) internal? -- exposed for testing purposes, for now... , dmFlip -- * converting to and from DualMap , toList, fromList, map -- * constructing a DualMap , empty, null, insert, union Happy code looks like this: module Data.DualMap ( -- * The @DualMap@ abstract type DualMap () -- * (?) internal? -- exposed for testing purposes, for now... , dmFlip -- * converting to and from DualMap , toList, fromList, map -- * constructing a DualMap , empty, null, insert, union Simple enough. I found this out by downloading DList [1] from hacakge and gutting it and replacing the code with my own code. When DList worked with 'cabal haddock' and mine didn't (when I tried to add some asterisks), I looked at the difference between the files and sure enough my parenthesis was on the wrong line. BTW I highly recommend DList as a starting place for a new Haskell project instead of hnop [2]. Jared. [1] http://hackage.haskell.org/package/dlist-0.5 [2] http://semantic.org/hnop/ On Wed, Aug 19, 2009 at 9:45 AM, Jared Updike jupd...@gmail.com wrote: I compiled and installed haddock-2.4.2 from the tarball source. Adding a few simple comments to the code here: https://dl.getdropbox.com/u/143480/doc/DualMap.hs and running haddock $ haddock -h -o doc Data/DualMap.hs Warning: Data.DualMap: could not find link destinations for: Data.Typeable.Typeable2 GHC.Base.Eq GHC.Show.Show GHC.Base.Ord GHC.Base.Bool Data.Set.Set yields: https://dl.getdropbox.com/u/143480/doc/Data-DualMap.html Things look good. (Note that this module only depends on libs that ship with GHC and no other source modules.) However, when I try to add sections (a la http://www.haskell.org/haddock/doc/html/ch03s04.html#id289234 ) in the comments with -- * test I get: $ haddock -h -o doc Data/DualMap.hs Data/DualMap.hs:20:0: parse error on input `-- * test' haddock: Failed to create dependency graph I have no idea where to begin getting this to work since this error message only tells me that Haddock.Interface.depanal returned Nothing (according to a grep of the haddock sources) but not how to stop the dependency analysis from failing. Perhaps I need some more command line arguments or references to missing link destinations in GHC/base/containers documentation or some haddock config file? Searching Google yielded plenty of cabal build errors of the same ilk for packages on hackage but nothing about how to fix them. Jared. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
2009/6/7 Dominic Steinitz domi...@steinitz.org:
Ha! It's yet another of haddock's quirks. If I replace -- ^ by -- then haddock
accepts {-#. I'll update the ticket you created.
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- ^ input
{-# UNPACK #-} !Int -- ^ bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- ^ the failure depth
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- input
{-# UNPACK #-} !Int -- bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- the failure depth
Haddock doesn't actually support comments on individual constructor
arguments. People often get confused by this, and the error message
isn't especially useful. We have a ticket for giving better error
messages:
http://trac.haskell.org/haddock/ticket/94
We also have a ticket about the feature itself:
http://trac.haskell.org/haddock/ticket/95
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
Dominic Steinitz wrote:
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
src/Data/Binary/Strict/IncrementalGet.hs:106:11:
parse error on input `{-# UNPACK'
This is a haddock error and I presume a bug in haddock.
Well I raised a bug here:
http://trac.haskell.org/haddock/ticket/109
Thats actually not the problem. I'm trying to build a debian package
for this thing and this haddock problem is preventing that.
Erik
This seems to be the problem:
http://hackage.haskell.org/trac/hackage/ticket/230. There's obviously a work
round for it as the haddock for the binary package builds (e.g.
http://hackage.haskell.org/packages/archive/binary/0.5.0.1/doc/html/Data-Binary-Get.html)
but I don't know what it is.
What's even more frustrating is one of the authors of has tried:
#ifndef __HADDOCK__
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- ^ input
{-# UNPACK #-} !Int -- ^ bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- ^ the failure depth
#endif
and haddock ignores this. And the binary package just has this (no ifdefs!):
-- Our internal buffer type
data Buffer = Buffer {-# UNPACK #-} !(ForeignPtr Word8)
{-# UNPACK #-} !Int-- offset
{-# UNPACK #-} !Int-- used bytes
{-# UNPACK #-} !Int-- length left
Perhaps one of the authors of binary can tell us their secret of success?
Dominic.
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
Dominic Steinitz dominic at steinitz.org writes:
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
Dominic Steinitz wrote:
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
src/Data/Binary/Strict/IncrementalGet.hs:106:11:
parse error on input `{-# UNPACK'
This is a haddock error and I presume a bug in haddock.
Well I raised a bug here:
http://trac.haskell.org/haddock/ticket/109
Ha! It's yet another of haddock's quirks. If I replace -- ^ by -- then haddock
accepts {-#. I'll update the ticket you created.
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- ^ input
{-# UNPACK #-} !Int -- ^ bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- ^ the failure depth
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- input
{-# UNPACK #-} !Int -- bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- the failure depth
Dominic.
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
Dominic Steinitz wrote:
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- ^ input
{-# UNPACK #-} !Int -- ^ bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- ^ the failure depth
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- input
{-# UNPACK #-} !Int -- bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- the failure depth
Thanks Dominic. Thats a workaround I can use.
Cheers,
Erik
--
--
Erik de Castro Lopo
http://www.mega-nerd.com/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
src/Data/Binary/Strict/IncrementalGet.hs:106:11:
parse error on input `{-# UNPACK'
Is this a bug? Is there any way to work around it?
This is a haddock error and I presume a bug in haddock. I don't know whether
cabal installs things if haddock fails. You could do ghc-pkg list and see what's
there. If it didn't install then you can install by hand:
1. Extract the sources and in that directory:
2. runghc Setup.lhs configure
3. runghc Setup.lhs build
4. runghc Setup.lhs install
You might want to do configure with --user - that's what cabal defaults to.
Dominic
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
Dominic Steinitz wrote:
Erik de Castro Lopo mle+hs at mega-nerd.com writes:
src/Data/Binary/Strict/IncrementalGet.hs:106:11:
parse error on input `{-# UNPACK'
Is this a bug? Is there any way to work around it?
This is a haddock error and I presume a bug in haddock.
Well I raised a bug here:
http://trac.haskell.org/haddock/ticket/109
I don't know whether cabal installs things if haddock fails.
Thats actually not the problem. I'm trying to build a debian package
for this thing and this haddock problem is preventing that.
Erik
--
--
Erik de Castro Lopo
http://www.mega-nerd.com/
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: haddock could be a pretty-printer?
2009/5/22 Maurício briqueabra...@yahoo.com: The new version of haddock makes use of GHC parser. How much of effort would take to make haddock generate pretty-print of the source code itself, (...) (...) Is this what you want or is there some reason why you want the code to be pretty-printed? I usually have to resort to braces or bad indenting to get code to parse, but I like to give it good presentation before publishing. I used to pretty-print my code using haskell-src-exts with great result, but that kills documentation. I think the plan is to extend haskell-src-exts to retain comments. But if you want something that works now, you could use the GHC API. It has support for getting the token stream of a module, which contains the comments as tokens. Using Haddock to do this is not a good idea, better use the GHC API directly. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock could be a pretty-printer?
The new version of haddock makes use of GHC parser. How much of effort would take to make haddock generate pretty-print of the source code itself, (...) (...) Is this what you want or is there some reason why you want the code to be pretty-printed? I usually have to resort to braces or bad indenting to get code to parse, but I like to give it good presentation before publishing. I used to pretty-print my code using haskell-src-exts with great result, but that kills documentation. Best, Maurício ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock GSoC project
Okay, I've written a draft Haddock-GSOC application: would any of you like to review it / suggest how it could be improved? (or should I just submit it to Google?) I'm particularly wondering whether my proposed time-line seems realistic. -Isaac * What is the goal of the project you propose to do? To improve Haddock, the Haskell documentation tool, both substantively in the short term and to be better factored in the long term. * Can you give some more detailed design of what precisely you intend to achieve? Resolve many Haddock Trac tickets. Specific projects: Make cross-package documentation work; and refactor the comment-parsing out of GHC and into the Haddock code-base. * What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones? In the first week I will get Haddock and GHC compilation and patch-making set up, fix some minor bugs and send/apply the fixes. Next I will start to determine and converse about the implementation difficulties with making Haddock work across packages. At the same time, I'll continue working on more minor bugs/features (increasing my familiarity with the code and with the coding process). By the end of June I hope to get cross-module docs working. [Is this a realistic goal?] By this time, I'll have some familiarity with the parsing code (having fixed some of its bugs/infelicities), and I can confront the problem of how to refactor the comment-parsing out of GHC. I can imagine I might only be able to find a partial solution easily, but I'll do whatever I have time for. Optimistic timeline to finish this by the end of July; if I get ahead of schedule, I'm sure I'll know enough about Haddock's infelicities by then to know other mini-projects that would be worth doing. For example, I could improve the layout of the index page Haddock generates (Python docs do it better, for reference, according to http://trac.haskell.org/haddock/ticket/70.) Due to the process of testing my changes, I might even write some documentation, if I see an atrociously documented function in some library :-) * In what ways will this project benefit the wider Haskell community? Better documentation (documentation that is less difficult to successfully write) makes everything flow more smoothly in source-code-land. Especially core (even Haskell-98) library documentation has broken multiple times due to Haddock deficiency, and other library authors suffer from everything from `type` annotations not working, to Haddock-2 parsing being more strict, to... every possible issue, really. The cross-package documentation failure specifically makes people reluctant to refactoring into smaller packages, even when that would increase code re-use. Making Haddock/GHC more composable should make it easier for everyone to make small improvements to Haddock, without delving into GHC as much. Perhaps it might even make possible some new tool different from Haddock that looks at information in comments, should someone desire such a thing. * What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you contributed to any other open source software? Been studying advanced courses in a related topic? I substantially improved Spiderweb Software's scenario-editor for Blades of Avernum (once they made it open-source), adding 3D support and other improvements. (C programming language). I worked on Battle for Wesnoth scenarios some, and I hacked on the C++ code for lexing/parsing their markup language, and I learned my lesson when I failed to coordinate successfully with the development team. :-) They used Doxygen to document their code, though it was not used nearly as thoroughly (at least, not back a few years ago) as a lot of Haskell code is documented today. I hacked on GHC, and this code has been committed: I improved the parsing of negative unboxed literals, and I refactored several places in the code that used language extensions unnecessarily. Also I've contributed to discussions on Haskell development mailing-lists over the years (leading to at least one bug-fix), and reported several more bugs in Trac as I ran into them while hacking in Haskell. I took an advanced-level Artificial Intelligence class in which I programmed in Haskell and got an A. I've read many research papers related to Haskell or compilation. I've used Darcs; I've used Linux and followed its open-source coordination travails for four years now (formerly I used Mac OS). I know (X)HTML and CSS well enough to write my own W3C-validated webpage (and my parents work in web-design so I hear a lot about it), so I should be able to work on Haddock's HTML-generating code easily. * In what ways do you envisage interacting with the wider Haskell community during your project? e.g. How would you seek help on something your mentor wasn't able to deal with? How will you get others
[Haskell-cafe] Re: Haddock GSoC project
Simon Marlow wrote: Obviously I think these tickets are important, since I wrote them :-) In terms of priority, I think #1567 is at the top: not having this harms our ability to reorganise and abstract things, it puts an arbitrary barrier between packages. It's possible my perspective is slightly skewed though, since most of the packages that are affected by this are in GHC's core package collection. still, -reorganization happens in others' packages too, and we want to encourage this! -everyone uses GHC's core packages and complains when the documentation is broken (and unfixable!) :-) but sure, we should find out if other people have higher priorities elsewhere. (cafe citizens and hackers, tell us what you think!) #1568 is just refactoring, but it's a high priority: we need to get this code out of GHC and back into Haddock. This is important for Haddock's long term future and general maintainability, though it won't have any visible effect on the way Haddock works. yes, I agree, things will keep being a little unpleasant until we do this. My intuition says that with 2-3 months I should have time to do this refactoring too, but then, I haven't actually spent a week figuring out just how difficult it is :-). Probably needs some refactoring the data-types that GHC emits comments as, and then possibly-more-complicated having Haddock parse and structure the Haddock-syntax within the comments (and as it relates to the actual code!) The index page really isn't working right now, since we added the search-box functionality it has become unusable for the GHC library docs (small libraries are ok). Thank goodness we have Hoogle and Hayoo. We should really just revert to the old A-Z links, I'm not sure if there's a Haddock ticket for this. maybe http://trac.haskell.org/haddock/ticket/70 is related? There's lot of other stuff that could be done. For instance I'd really like someone with some CSS expertise to have another go at Haddock's HTML layout. I've done some manual HTML/CSS on my own website (W3C validated!)... don't know if it comes anywhere near expertise though :-) One random haddock problem I remember bothering me recently is: no view source link on each instance in the list of instances for a data-type (so I clicked a nearby view source and scrolled to find the instance source, which was in the same module) -Isaac ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock GSoC project
Isaac Dupree wrote: I'm interested in being a GSoC student, and the Haddock-related tickets looked like a good place to start http://hackage.haskell.org/trac/summer-of-code/ticket/1567 http://hackage.haskell.org/trac/summer-of-code/ticket/1568 http://hackage.haskell.org/trac/summer-of-code/ticket/1569 haddock could use some love! And I love documentation. I think I'd start by hacking on some relatively easy Haddock tickets to find my way around the code and the hacking process. Then it might be time to move into one of the bigger projects (I'm tempted to say #1567, Haddock: allow documentation to propagate between packages), depending on priorities; probably still working on some smaller but important Haddock tickets. Then it depends how much time we have left in the summer, there's a lot that can be done! - I've hacked on the GHC lexing/parsing code a bit, and I know darcs, haskell, etc., and I've been around watching on mailing-lists since before Haddock 2.x, so I feel like I have a fair amount of context with which to approach this project. What do you think, is this a good project to look towards? What's the next step... should I elaborate my proposal by looking at Haddock tickets and their priorities? But I should have your feedback first; what do the mentors, or the Haskell community, want most to be improved about Haddock? Obviously I think these tickets are important, since I wrote them :-) In terms of priority, I think #1567 is at the top: not having this harms our ability to reorganise and abstract things, it puts an arbitrary barrier between packages. It's possible my perspective is slightly skewed though, since most of the packages that are affected by this are in GHC's core package collection. #1568 is just refactoring, but it's a high priority: we need to get this code out of GHC and back into Haddock. This is important for Haddock's long term future and general maintainability, though it won't have any visible effect on the way Haddock works. The index page really isn't working right now, since we added the search-box functionality it has become unusable for the GHC library docs (small libraries are ok). Thank goodness we have Hoogle and Hayoo. We should really just revert to the old A-Z links, I'm not sure if there's a Haddock ticket for this. There's lot of other stuff that could be done. For instance I'd really like someone with some CSS expertise to have another go at Haddock's HTML layout. Cheers, Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Markup
Jonathan Cast wrote: NB: This example is *precisely* why I will never adopt MathML as an authoring format. Bowing and scraping at the alter of W3C is not worth using such a terrible syntax, not ever. (Indented, that's math mrow msup mix/mi mn2/mn /msup mo+/mo mrow mn4/mn moInvisibleTimes;/mo mix/mi /mrow mo+/mo mn4/mn /mrow /math Which is still unforgivably horrible. I *think* it's trying to say $x^2 + 4x + 4$, but I'm not confident even of that. Yeah, MathML looks like a machine-only format to me, begging the question why they don't use a more compact format. I'm also unconvinced it's actually easier to parse than $x^2 + 4x + 4$.) While parsing is a solved problem in theory, a lot of people use some regular expression kludges or similar atrocities in practice. Writing a proper parser is too complicated if your language doesn't have parser combinators. :) Regards, apfelmus -- http://apfelmus.nfshost.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Markup
On Fri, 2009-02-13 at 11:08 +0100, Heinrich Apfelmus wrote: Jonathan Cast wrote: NB: This example is *precisely* why I will never adopt MathML as an authoring format. Bowing and scraping at the alter of W3C is not worth using such a terrible syntax, not ever. (Indented, that's math mrow msup mix/mi mn2/mn /msup mo+/mo mrow mn4/mn moInvisibleTimes;/mo mix/mi /mrow mo+/mo mn4/mn /mrow /math Which is still unforgivably horrible. I *think* it's trying to say $x^2 + 4x + 4$, but I'm not confident even of that. Yeah, MathML looks like a machine-only format to me, begging the question why they don't use a more compact format. I'm also unconvinced it's actually easier to parse than $x^2 + 4x + 4$.) While parsing is a solved problem in theory, a lot of people use some regular expression kludges or similar atrocities in practice. Yeah, we even seem to have adopted one of their syntaxen [markdown]. Writing a proper parser is too complicated if your language doesn't have parser combinators. :) Haddock, I believe, is written in a language that does. If MathML output is desired at some point (e.g., if browsers start doing better at rendering it than at rendering images with TeX source-code alt-texts :) the I think Haddock will still be capable of handling a reasonable input language. jcc ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Markup
What about making a SoC out of the problem? A mathematical markup language that is easily written as well as valid Haskell, executable within reason, compilable into mathML (think backticks) and would revolutionise the typeset quality of literate programming? -- (c) this sig last receiving data processing entity. Inspect headers for copyright history. All rights reserved. Copying, hiring, renting, performance and/or quoting of this signature prohibited. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Markup
On Fri, 13 Feb 2009, Achim Schneider wrote: What about making a SoC out of the problem? A mathematical markup language that is easily written as well as valid Haskell, executable within reason, compilable into mathML (think backticks) and would revolutionise the typeset quality of literate programming? That's what I just proposed in the SoC thread. Thanks for seconding! :-) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Markup
On Tue, 2009-02-10 at 12:39 +0100, Henning Thielemann wrote:
Heinrich Apfelmus schrieb:
Henning Thielemann wrote:
I want for long to write math formulas in a paper in Haskell. Actually,
lhs2TeX can do such transformations but it is quite limited in handling
of parentheses and does not support more complicated transformations
(transforming prefix notation in infix notation or vice versa with
minimal parentheses).
I would like to write
sumFor [0..n] (\i - i^2)
(with sumFor xs f = sum $ map f xs)
which is rendered as
\sum_{i=0}^{n} i^2
or
integrate 1000 (a,b) (\t - f t)
to be rendered as
\int_a^b f(t) \dif t
Neat idea! Can't you do implement this as a DSL?
sumFor x xs f =
\sum_{ ++ x ++ = ++ head xs ++ }^{ ++ last xs ++ }
++ f x
My original idea was to use the formulas in papers both for typesetting
and for unit testing. Thus, when you state that a function fulfills a
law, that it can be automatically tested by QuickCheck, that this at
least true for some instances.
The same would be useful for Haddock documentation. I remember that
someone proposed to permit Haddock to expose the implementation of some
functions as examples or as unit-tests/laws. Now we could extend this
idea to allow Haddock not only to expose the implementation of
functions, but also to tell Haddock how to render its implementation.
If we want to tell haddock how to render an implementation, surely we
use a derivative of lhs2tex. It requires minimal markup in the standard
case (just spacing for alignment) and has a nice set of standard
presentation rules and allows extending that with formatting directives.
It would not let you write complex display mode maths like
\sum_{i=0}^{n} i^2
but for code, and laws and proofs that look mostly like code it's really
nice.
Duncan
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Markup
Heinrich Apfelmus schrieb:
Henning Thielemann wrote:
I want for long to write math formulas in a paper in Haskell. Actually,
lhs2TeX can do such transformations but it is quite limited in handling
of parentheses and does not support more complicated transformations
(transforming prefix notation in infix notation or vice versa with
minimal parentheses).
I would like to write
sumFor [0..n] (\i - i^2)
(with sumFor xs f = sum $ map f xs)
which is rendered as
\sum_{i=0}^{n} i^2
or
integrate 1000 (a,b) (\t - f t)
to be rendered as
\int_a^b f(t) \dif t
Neat idea! Can't you do implement this as a DSL?
sumFor x xs f =
\sum_{ ++ x ++ = ++ head xs ++ }^{ ++ last xs ++ }
++ f x
My original idea was to use the formulas in papers both for typesetting
and for unit testing. Thus, when you state that a function fulfills a
law, that it can be automatically tested by QuickCheck, that this at
least true for some instances.
The same would be useful for Haddock documentation. I remember that
someone proposed to permit Haddock to expose the implementation of some
functions as examples or as unit-tests/laws. Now we could extend this
idea to allow Haddock not only to expose the implementation of
functions, but also to tell Haddock how to render its implementation.
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Markup
Henning Thielemann wrote:
I want for long to write math formulas in a paper in Haskell. Actually,
lhs2TeX can do such transformations but it is quite limited in handling
of parentheses and does not support more complicated transformations
(transforming prefix notation in infix notation or vice versa with
minimal parentheses).
I would like to write
sumFor [0..n] (\i - i^2)
(with sumFor xs f = sum $ map f xs)
which is rendered as
\sum_{i=0}^{n} i^2
or
integrate 1000 (a,b) (\t - f t)
to be rendered as
\int_a^b f(t) \dif t
Neat idea! Can't you do implement this as a DSL?
sumFor x xs f =
\sum_{ ++ x ++ = ++ head xs ++ }^{ ++ last xs ++ }
++ f x
Regards,
apfelmus
--
http://apfelmus.nfshost.com
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
I did work on this and i simplified the code a lot fixing inconsistencies and making more explicit what how each component contributes to the arguments to haddock. Aside from this, should we also do the unliting and cpp from Cabal on the sources passed to HsColour? On Fri, Feb 6, 2009 at 11:27 PM, Duncan Coutts duncan.cou...@worc.ox.ac.uk wrote: On Fri, 2009-02-06 at 11:48 +0100, David Waern wrote: 2009/2/6 Alistair Bayley alist...@abayley.org: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) Sorry, my mistake. I pasted the error message from a different problem. This is the error I get from haddock: C:\bayleya\eclipse\workspace\takusen\srchaddock -h --odir=doc Test/Haddock.lhs Cannot find documentation for: $named_block Okay, then I understand. My guess is (without looking at ghc code) that ghc just throws the literate comments away before lexing the file. This means that the Haddock comments won't be recognized. As you say, there is also an unlitter in Cabal. I don't remember if it is invoked when using Haddock 2, but if it is, it would solve this problem. Yes, against my better judgement the code in Cabal for haddock-2.x does not run cpp or unliting like it does for haddock-0.x. Instead it assumes that haddock-2.x will do all the cpp and unliting itself. Obviously this mean the special unliting mode that Cabal provides is not usable with haddock-2.x. The solution is to do the pre-processing the same for haddock-0.x and 2.x. Generally the haddock code in Cabal is a horrible inconsistent mess. I believe Andrea Vezzosi has been looking at rewriting it, which is good news. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
On Sun, 2009-02-08 at 19:18 +0100, Andrea Vezzosi wrote: I did work on this and i simplified the code a lot fixing inconsistencies and making more explicit what how each component contributes to the arguments to haddock. Much appreciated. Aside from this, should we also do the unliting and cpp from Cabal on the sources passed to HsColour? Hmm. I thought it did already :-) Well, I know it runs happy, hsc2hs etc. Someone was complaining the other day that the hscolour output run on the result of happy is not really readable, but then it's not clear if running it on the happy input would be any better. For the particular case of .lhs and cpp, I hope we'd get better hscolour output by not running unlit or cpp first. Malcolm says it'll at least do something. So it seems worth checking which ends up looking more useful. Duncan On Fri, Feb 6, 2009 at 11:27 PM, Duncan Coutts Yes, against my better judgement the code in Cabal for haddock-2.x does not run cpp or unliting like it does for haddock-0.x. Instead it assumes that haddock-2.x will do all the cpp and unliting itself. Obviously this mean the special unliting mode that Cabal provides is not usable with haddock-2.x. The solution is to do the pre-processing the same for haddock-0.x and 2.x. Generally the haddock code in Cabal is a horrible inconsistent mess. I believe Andrea Vezzosi has been looking at rewriting it, which is good news. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
2009/2/6 Duncan Coutts duncan.cou...@worc.ox.ac.uk: Yes, against my better judgement the code in Cabal for haddock-2.x does not run cpp or unliting like it does for haddock-0.x. Instead it assumes that haddock-2.x will do all the cpp and unliting itself. Obviously this mean the special unliting mode that Cabal provides is not usable with haddock-2.x. The solution is to do the pre-processing the same for haddock-0.x and 2.x. Generally the haddock code in Cabal is a horrible inconsistent mess. I believe Andrea Vezzosi has been looking at rewriting it, which is good news. In Distribution.Simple.Haddock, in the haddock function we have: withLib pkg_descr () $ \lib - do let bi = libBuildInfo lib modules = PD.exposedModules lib ++ otherModules bi inFiles - getLibSourceFiles lbi lib unless isVersion2 $ mockAll bi inFiles So I guess the easiest thing to do right now is remove the unless isVersion2 $ . I'm testing this at the moment, so when I get it working (or not) I'll let you know, and maybe send a patch. Alistair ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock
2009/2/6 Max Rabkin max.rab...@gmail.com: On Thu, Feb 5, 2009 at 4:25 PM, David Waern david.wa...@gmail.com wrote: As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. I personally find it useful to have Haddock comments readable in the source. And aren't there security issues, too? So we'd have to have an option to disable them, which would have to be on by default, and basically they would be disabled by everybody but the writers of the comments themselves. I think you can invoke any command using Setup.hs and Cabal already. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
2009/2/6 Alistair Bayley alist...@abayley.org: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) Sorry, my mistake. I pasted the error message from a different problem. This is the error I get from haddock: C:\bayleya\eclipse\workspace\takusen\srchaddock -h --odir=doc Test/Haddock.lhs Cannot find documentation for: $named_block Okay, then I understand. My guess is (without looking at ghc code) that ghc just throws the literate comments away before lexing the file. This means that the Haddock comments won't be recognized. As you say, there is also an unlitter in Cabal. I don't remember if it is invoked when using Haddock 2, but if it is, it would solve this problem. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock
On Fri, 2009-02-06 at 09:40 +0100, David Waern wrote: 2009/2/6 Max Rabkin max.rab...@gmail.com: On Thu, Feb 5, 2009 at 4:25 PM, David Waern david.wa...@gmail.com wrote: As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. I personally find it useful to have Haddock comments readable in the source. And aren't there security issues, too? So we'd have to have an option to disable them, which would have to be on by default, and basically they would be disabled by everybody but the writers of the comments themselves. I think you can invoke any command using Setup.hs and Cabal already. It's not a question of what's possible. It's a question of how hard it is to audit your code. Do I just have to read your build system (Setup.hs and its import tree, and maybe the Cabal file)? Or do I have to scan the source code for dubious constructs (unfortunately, we already have this issue with Template Haskell)? Most programs have source code that is much larger than their build systems. jcc ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
[1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) Sorry, my mistake. I pasted the error message from a different problem. This is the error I get from haddock: C:\bayleya\eclipse\workspace\takusen\srchaddock -h --odir=doc Test/Haddock.lhs Cannot find documentation for: $named_block Alistair ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
2009/2/6 Alistair Bayley alist...@abayley.org: I have this test case for Haddock (2.3.0): -- | Module : Test.Haddock Copyright : (c) 2009 Alistair Bayley License : BSD-style Maintainer : alist...@abayley.org Stability : stable Portability : portable Test case for Haddock. module Test.Haddock ( -- $named_block Fail(..) ) where data Fail = Fail | Succeed $named_block This is some hadock documentation. -- This fails with: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
On Fri, 2009-02-06 at 11:48 +0100, David Waern wrote: 2009/2/6 Alistair Bayley alist...@abayley.org: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) Sorry, my mistake. I pasted the error message from a different problem. This is the error I get from haddock: C:\bayleya\eclipse\workspace\takusen\srchaddock -h --odir=doc Test/Haddock.lhs Cannot find documentation for: $named_block Okay, then I understand. My guess is (without looking at ghc code) that ghc just throws the literate comments away before lexing the file. This means that the Haddock comments won't be recognized. As you say, there is also an unlitter in Cabal. I don't remember if it is invoked when using Haddock 2, but if it is, it would solve this problem. Yes, against my better judgement the code in Cabal for haddock-2.x does not run cpp or unliting like it does for haddock-0.x. Instead it assumes that haddock-2.x will do all the cpp and unliting itself. Obviously this mean the special unliting mode that Cabal provides is not usable with haddock-2.x. The solution is to do the pre-processing the same for haddock-0.x and 2.x. Generally the haddock code in Cabal is a horrible inconsistent mess. I believe Andrea Vezzosi has been looking at rewriting it, which is good news. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock
Hi everyone, I received this question from Lennart Augustsson (via Simon M) and thought I'd send out an inquiry to the Haskell community in general (Lennart, I hope you don't mind): Lennart writes: We have some local patches for haddock that extends the blah syntax so you can put TeX formulae in the documentation. It looks like, ! LaTeX stuff here !, but I'd like to extend it so you can process the string with any command. Are you interested in folding this into the main branch? So the question is about extending the Haddock markup language. When modifying the language we should think about the tension between familiarity, presentation features (pictures, math, whatever) and visual portability across different mediums (HTML, ghci, IDE tooltips, etc). And here I should say that Haddock already supports pictures using the url syntax. IMHO, adding ! LaTeX ! for TeX math is fine, because: - math in documentation is often useful - if you're going to write math, you need a format, even when the medium is plain text as in ghci. - TeX formulae seem to be relatively widely used and understood. As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. There was also a thread about Haddock markup on haskell-cafe@ about a year ago, which originated with the interesting idea of using Markdown (or a Pandoc-extended version of it) instead of the current language: http://www.mail-archive.com/haskell-cafe@haskell.org/msg38054.html I think the original idea there is pretty nice, but let's first focus on the current markup language in order to answer Lennart's question. That thread contains some useful opinions on this matter, also. So, any comments? :) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock
On Thu, Feb 5, 2009 at 4:25 PM, David Waern david.wa...@gmail.com wrote: As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. I personally find it useful to have Haddock comments readable in the source. And aren't there security issues, too? So we'd have to have an option to disable them, which would have to be on by default, and basically they would be disabled by everybody but the writers of the comments themselves. --Max ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
RE: [Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
Hi Simon, http://joyful.com/repos/darcs-sm/api-doc is a mashup of haddock, hoogle and hscolour (and darcsweb, darcs-graph - see http://joyful.com/repos). I can see the Haddock information, but not the Hoogle/HsColour mashup. I'm using Firefox 3. Am I missing something? How do you get started with a Hoogle query? had time to work on this, currently I hard-code the target in hoogle and munge the haddock output slightly (see recent patch in darcs-unstable). I believe you emailed me privately with a question about pointing at haddock documentation from Hoogle. I'm currently a bit out of sync with emails as I've just moved house, don't yet have internet, and can't check my gmail account from work. The answer, from what I can remember of the question, is: How do I get Hoogle to point at a particular documentation repo? The answer is to add a line similar to: @haddock http://hackage.haskell.org/packages/archive/Cabal/latest/doc/html/ to the Text file you get out of haddock --hoogle. You can also add an @hackage url, which is treated as the home page of the package. Thanks Neil == Please access the attached hyperlink for an important electronic communications disclaimer: http://www.credit-suisse.com/legal/en/disclaimer_email_ib.html == ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
Hi Neil.. my apologies, my nightly cron script clobbered it. Please try now, same url: http://joyful.com/repos/darcs-sm/api-doc You should see three panes with hoogle in the lower left. The answer is to add a line similar to: @haddock http://hackage.haskell.org/packages/archive/Cabal/latest/doc/html/ to the Text file you get out of haddock --hoogle. You can also add an @hackage url, which is treated as the home page of the package. Aha, I had not detected that at all. Thanks for the tip. Also thanks to you and the haddock hscolour authors for such fine tools. -Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
Hi Neil.. my apologies, my nightly cron script clobbered it. Please try now, same url: http://joyful.com/repos/darcs-sm/api-doc It seems the Contents link embeds the outer frame into the right-hand side inner frame. Otherwise, it looks nice! Sean ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
Hi The answer is to add a line similar to: @haddock http://hackage.haskell.org/packages/archive/Cabal/latest/doc/html/ to the Text file you get out of haddock --hoogle. You can also add an @hackage url, which is treated as the home page of the package. Aha, I had not detected that at all. Thanks for the tip. Also thanks to you and the haddock hscolour authors for such fine tools. It's entirely undocumented, and not a great interface - my hope is that one day cabal will pass some --hoogle-extra flags or something to haddock, but I've not yet decided how packages should specify where they live - if you have any suggestions do let me know. For your example page, its very nice. Perhaps, for the bottom left Hoogle box, it would be easier if you used the code snipped: form action='http://haskell.org/hoogle/' method='get' input name='hoogle' id='hoogle' type='text' value= / input id='submit' type='submit' value='Search' / /form That way the interface should look a bit nicer, as you don't need such a large amount of space for a search box and you can format it the way you want. Thanks Neil ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
that one day cabal will pass some --hoogle-extra flags or something to haddock, but I've not yet decided how packages should specify where they live - if you have any suggestions do let me know. Will do.. I've yet to come to grips with cabal, still in makefile land as yet.. For your example page, its very nice. Perhaps, for the bottom left Hoogle box, it would be easier if you used the code snipped: Works well, thanks! I've also put it at the top of the haddock pane, so the third pane could be dropped ? Not sure which is better. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock + Hoogle == Javadoc on steroids
Taking this to haskell-cafe.. http://joyful.com/repos/darcs-sm/api-doc is a mashup of haddock, hoogle and hscolour (and darcsweb, darcs-graph - see http://joyful.com/repos). It's rough but quite useful - a few minutes here gave me a much better understanding of the big picture of darcs code. By alternating shift enter in the contents pane I could browse quickly through all modules. Improvement: one could do a lot of useful magic with javascript. But it would be more powerful to improve the tools, eg I'd like if haddock had frames/no-frames built in and hoogle could be made to work in either case. I haven't had time to work on this, currently I hard-code the target in hoogle and munge the haddock output slightly (see recent patch in darcs-unstable). As you say it would be great to keep improving this area and baking it into our tools and infrastructure. Highly accessible and efficient docs and code browsing tools help a lot! On Sep 27, 2008, at 1:49 PM, Jason Dagit wrote: Simon, I'm wondering if you could find a way to make it trivial for people using cabal to combine haddock and hoogle the way you have for darcs? Some ideas: 1) Depend entirely on cabal for the auto setup of things 2) Provide the framed interface on your webpage also has a layout in emacs (so people can use either web or emacs) 3) Package it so that people just 'cabal install hoodock hoddock ./src' and then they are done for 90% of cases 4) Provide demos for darcs and something else large like GHC What do you think? If you need help with it, I'm sure there are tons of people on Haskell-Cafe that would really dig this and help you with it. Thanks, I love it! Jason Thanks! -Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock compilation problem
Ronald Guida wrote: I just upgraded to ghc-6.8.3, using a linux binary, and I am having a problem compiling Haddock. Haddock 2.1.0 and Haddock 2.0.0.0 both fail to build under ghc-6.8.3, but they both build successfully with ghc-6.8.2. I don't know if this is a Haddock problem, or a GHC problem, or perhaps something else entirely? Here is the error I'm getting. It is the same error for either version of Haddock. [15 of 24] Compiling Haddock.GHC.Typecheck ( src/Haddock/GHC/Typecheck.hs, dist/build/haddock/haddock-tmp/Haddock/GHC/Typecheck.o ) src/Haddock/GHC/Typecheck.hs:82:4: Constructor `HsModule' should have 7 arguments, but has been given 8 In the pattern: HsModule _ _ _ _ _ mbOpts _ _ In a pattern binding: HsModule _ _ _ _ _ mbOpts _ _ = unLoc parsed snip I managed to fix this with a bit of hacking: 1) add import FastString to the top of the file 2) remove one of the _'s before mbOpts on that line that gives the error 3) on line 72 of the original file (probably 73 after step 1), insert 'fmap unpackFS' before 'mbOpts'. I now get some sort of System.Process-related link error, though. YMMV. libHSghc.a(SysTools.o)(.text+0x7200):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_a6_closure' libHSghc.a(SysTools.o)(.text+0x75c5):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_lvl1_closure' libHSghc.a(SysTools.o)(.text+0xa6df):fake: undefined reference to `__stginit_processzm1zi0zi0zi1_SystemziProcess_' libHSghc.a(SysTools.o)(.text+0x7215):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcessziInternals_a3_info' libHSghc.a(SysTools.o)(.text+0x75d4):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_a8_info' libHSghc.a(SysTools.o)(.data+0xcf8):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_lvl1_closure' libHSghc.a(SysTools.o)(.data+0xcfc):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_a8_closure' libHSghc.a(SysTools.o)(.data+0xd00):fake: undefined reference to `processzm1zi0zi0zi1_SystemziProcess_a6_closure' ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock compilation problem
Matti Niemenmaa wrote: I now get some sort of System.Process-related link error, though. YMMV. Audrey Tang gave me the fix for this on the IRC channel: passing --ghc-option=-package process-1.0.0.1 dealt with that. It appears that it was all for naught, though: running the haddock binary on pretty much anything results in Segmentation fault/access violation in generated code or a downright crash. I suppose I'll leave this to the Haddock developers, then. g ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock compilation problem
I have added ticket #18 to the Haddock Trac. http://trac.haskell.org/haddock/wiki ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Help Required
David Waern david.waern at gmail.com writes: 2008/3/24, Dominic Steinitz dominic.steinitz at blueyonder.co.uk: What should I be using for the file name for the read-interface option in haddock? You must use a file that is on your own hard drive and that is generated with version 2.0 of Haddock, since that is what you're using. The interface file format was changed in Haddock 2.0 due its use of GHC data types, so you can't use 0.x interface files. You need to generate base.haddock with Haddock 2.0. One way to do that, is to make sure Haddock 2.0 is installed, then get the GHC 6.8.2 sources (with core libs) and build that with Haddock docs enabled. Hope this helps, David Thanks I've done this [EMAIL PROTECTED]:~/asn15/asn1 haddock -v -html -o hdoc Pretty.hs -B /usr/lib/ghc-6.8.2 --optghc=-fglasgow-exts --read-interface=http://www.haskell.org/ghc/docs/6.8.2/html/libraries/base,/home/dom/ghc-6.8.2/libraries/base/dist/doc/html/base/base.haddock but now when I click on e.g. Integer I get directed to http://www.haskell.org/ghc/docs/6.8.2/html/libraries/base/GHC-Num.html#t%3AInteger which doesn't exist. Integer actually exists in http://www.haskell.org/ghc/docs/6.8.2/html/libraries/base/Prelude.html#t%3AInteger What do I need to do to get haddock to point at the right links? Dominic. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: documenting parameters of functional arguments
Henning Thielemann wrote:
I like to write documentation comments like
fix ::
( a {- ^ local argument -}
- a {- ^ local output -} )
- a {- ^ global output -}
but Haddock doesn't allow it. Or is there a trick to get it work?
Haddock only supports documenting the top-level arguments of a function
right now.
Cheers,
Simon
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock not finding base lib docs -- $topdir ?
[ moving to haskell-cafe@haskell.org ] Claus Reinke wrote: This is due to the way GHC is installed on Windows, the package database doesn't have hardcoded pathnames, the idea being that you can move your GHC anywhere in the filesystem and it will still work. this is an essential feature (for instance, running GHC from a USB or network drive, or just unpacking snapshots without using installers), please do not start splicing in absolute paths! Don't worry, we don't intend to do that. Unfortunately this means that Haddock can't find the documentation for the packages. this part I do not understand - if GHC and ghc-pkg can find the packages, why can't Haddock? wouldn't it just be a case of making $topdir be in a fixed relationship to the output of ghc --print-libdir? well yes, but Haddock doesn't invoke 'ghc --print-libdir'. I think it would be better for ghc-pkg to hide $topdir from everyone by replacing it with its value in any ghc-pkg output. After all, $topdir is just a hack to make the GHC tree location-independent on Windows, it's not a documented feature of the package system. or should there be a way to query ghc-pkg for the list of package location roots? as you say, the main docs will be in a known location relative to GHC, but perhaps docs in general should be be in a known location relative to their packages, which ghc-pkg (or other tools for other implementations) should be able to locate? One workaround is to specify the paths by hand, using Haddock's --read-interface flag. You're using Haddock via Cabal though, so that doesn't work too well. The other workaround is to find GHC's package.conf file and replace the string $topdir with the literal path (c:/ghc/ghc-6.6 in your case - perhaps you have to append /doc for the haddock fields, though). will all docs be moved into `ghc --print-libdir`\\doc? No. Docs can be installed wherever you like. Cabal has a policy for installation locations on Windows, which you can override if you want. what about local/user package databases? Same here, you can install things wherever you like. In fact, installing things inside the GHC tree isn't recommended. Cheers, Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock seems to generate wrong types in newtype deriving
Brian Hulley wrote: Hi - I have the following code: data MState = MState -- details omitted type MonadStateMState = MonadState MState -- necessary for Haddock newtype ManagerM a = ManagerM (StateT MState IO a) deriving (Monad, MonadIO, MonadStateMState) which means that ManagerM is an instance of Monad, MonadIO, and MonadState MState. However, the Haddock docs look like: data ManagerM a Instances ??? a = Monad (ManagerM a) ??? a = MonadIO (ManagerM a) ??? a = MonadStateMState (ManagerM a) which doesn't seem at all right to me. I'd have thought it should say: data ManagerM a Instances Monad ManagerM MonadIO ManagerM MonadStateMState ManagerM Is this just a bug in Haddock or am I misunderstanding something about Haskell? It's a bug / missing feature in Haddock. Haddock is basically pretty dumb when it comes to understanding Haskell code; it knows about the syntax and the module system, and that's about all. It makes a half-hearted attempt to figure out what instances you get from deriving clauses, but it's not complete, and you've encountered a case it doesn't handle. One day Haddock will be built on top of the GHC API, and all this will be fixed... Cheers, Simon ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock seems to generate wrong types in newtype deriving
Simon Marlow wrote: Brian Hulley wrote: Hi - I have the following code: [snip] Is this just a bug in Haddock or am I misunderstanding something about Haskell? It's a bug / missing feature in Haddock. Haddock is basically pretty dumb when it comes to understanding Haskell code; it knows about the syntax and the module system, and that's about all. It makes a half-hearted attempt to figure out what instances you get from deriving clauses, but it's not complete, and you've encountered a case it doesn't handle. One day Haddock will be built on top of the GHC API, and all this will be fixed... Thanks - I'm glad it's not just me! In the meantime, I found a better workaround (since the type decl using a class name is not legal Haskell) is just to use -cpp to preprocess for both ghc and haddock so that haddock sees explicitly defined dummy instances instead of a newtype deriving clause, then perfect results are obtained... :-) Regards, Brian. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problems
Daniel Fischer wrote: Hi all, I've just installed haddock-0.7, nice, but... haddock -o h7doc -h -D h7doc/fusi.haddock --use-package=base Verwaltung.hs Teams.hs Stats.hs Match.hs Main.hs Liga.hs Item.hs Helpers.hs Datum.hs Warning: Helpers: could not find link destinations for: GHC.Base.Int GHC.Base.String GHC.Show.Show Data.Maybe.Maybe GHC.Base.Eq GHC.Base.Bool and so on. Same problem, if I use -i/usr/.../base.haddock instead of try --read-interface=/usr/.../base (and more such entries for other packages) Cheers Christian ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problems
Daniel Fischer wrote: Hi all, I've just installed haddock-0.7, nice, but... haddock -o h7doc -h -D h7doc/fusi.haddock --use-package=base Verwaltung.hs Teams.hs Stats.hs Match.hs Main.hs Liga.hs Item.hs Helpers.hs Datum.hs Warning: Helpers: could not find link destinations for: GHC.Base.Int GHC.Base.String GHC.Show.Show Data.Maybe.Maybe GHC.Base.Eq GHC.Base.Bool and so on. Same problem, if I use -i/usr/.../base.haddock instead of try --read-interface=/usr/.../base (and more such entries for other packages) Sorry, that alone is not enough (and the same of what you've tried). I've also a magic -s path/%F on my haddock line. Cheers Christian ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problems
Daniel Fischer wrote: Hi all, I've just installed haddock-0.7, nice, but... haddock -o h7doc -h -D h7doc/fusi.haddock --use-package=base Verwaltung.hs Teams.hs Stats.hs Match.hs Main.hs Liga.hs Item.hs Helpers.hs Datum.hs Warning: Helpers: could not find link destinations for: GHC.Base.Int GHC.Base.String GHC.Show.Show Data.Maybe.Maybe GHC.Base.Eq GHC.Base.Bool and so on. Same problem, if I use -i/usr/.../base.haddock instead of I hope the following is correct now: --read-interface=/usr/../libraries/base,/usr/../libraries/base/base.haddock (-s only supplies links to your own source code) Cheers Christian ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock Problems
Am Mittwoch, 8. März 2006 12:06 schrieben Sie: Daniel Fischer wrote: Hi all, I've just installed haddock-0.7, nice, but... haddock -o h7doc -h -D h7doc/fusi.haddock --use-package=base Verwaltung.hs Teams.hs Stats.hs Match.hs Main.hs Liga.hs Item.hs Helpers.hs Datum.hs Warning: Helpers: could not find link destinations for: GHC.Base.Int GHC.Base.String GHC.Show.Show Data.Maybe.Maybe GHC.Base.Eq GHC.Base.Bool and so on. Same problem, if I use -i/usr/.../base.haddock instead of I hope the following is correct now: --read-interface=/usr/../libraries/base,/usr/../libraries/base/base.haddock I had that, first with -i/usr... then also with --read-interface=..., no difference haddock -h -o dock -D dock/fusi.haddock --read-interface=/usr/local/lib/ghc-6.4.1/libraries/base,/usr/local/lib/ghc-6.4.1/libraries/base/base.haddock *.hs Warning: Helpers: could not find link destinations for: GHC.Base.Int GHC.Base.String GHC.Show.Show Data.Maybe.Maybe GHC.Base.Eq GHC.Base.Bool ... (-s only supplies links to your own source code) Cheers Christian Any other ideas? Thanks, Daniel -- In My Egotistical Opinion, most people's C programs should be indented six feet downward and covered with dirt. -- Blair P. Houghton ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
