haddock doesn't support standalone deriving?

[claus]

also, I'd like to be able to build haddock 2 with ghc head.

[claus]

Apparently, the latest darcs haddock builds with ghc head again (thanks) and supports standalone deriving (at least it doesn't choke on it, haven't been able to verify yet that the instances are recorded).

But that leaves me with another problem: the __HADDOCK__ macro doesn't give me the haddock version, so how do I comment out standalone deriving for all but the latest darcs haddock?

[claus]

actually, the haddock version alone wouldn't be sufficient, one also needs to know what ghc version that haddock version was built with..

since a haddock 2 built with a different ghc version won't even work, one might check against haddock version and ghc version, and assume that haddock was build with the same ghc version..

as usual, feature-based macros would be an improvement over version-based macros (something like HADDOCK_<language feature>, where <language feature> is the usual LANGUAGE pragma code).

[waern]

I think Cabal could assign the version to the __HADDOCK__ macro.

You'd say #ifdef __HADDOCK__ to test for Haddock and #if __HADDOCK__ == 202 to test for version 2.2.*

Since the macro is not just needed during a Haddock invocation, but also during a normal compile, I think it should be defined by Cabal. Users of standalone-Haddock can always define symbols by passing GHC flags to Haddock.

Claus, what do you think?

[claus]

Replying to waern:

I think Cabal could assign the version to the __HADDOCK__ macro.

All generators of __HADDOCK__ need to agree on this - was this passed manually before Cabal?

You'd say #ifdef __HADDOCK__ to test for Haddock and #if __HADDOCK__ == 202 to test for version 2.2.*

It would be more complicated than that:

#ifdef __HADDOCK__
#if __HADDOCK__ >= 202
#if defined(__GLASGOW_HASKELL__) && __GLASGOW_HASKELL__ > 610
-- (1) near normal code, with fewer haddock tricks (for haddock's ghc)
#else
-- (2) haddock tricks for new haddock, built with old ghc
#endif
#else
-- (3) haddock tricks for old haddock
#endif
#else
-- (4) normal code
#endif

Assuming this is even approximately right, it looks rather complicated. Especially the bit about __GLASGOW_HASKELL__ inside __HADDOCK__ possibly referring to a different version than outside..

Since the macro is not just needed during a Haddock invocation, but also during a normal compile, I think it should be defined by Cabal. Users of standalone-Haddock can always define symbols by passing GHC flags to Haddock.

GHC seems to define its own macros, and that might also be the preferred option for haddock, reducing the chance of inconsistencies.

[anonymous]

Replying to claus:

Replying to waern:

I think Cabal could assign the version to the __HADDOCK__ macro.

All generators of __HADDOCK__ need to agree on this - was this passed manually before Cabal?

Yes, I think so. But those that break because the new Haddock needs the processed code to compile have been broken since the introduction of 2.0.0.0. Tools that test for this symbol can continue to do so, and if they break, it's not because of this change.

You'd say #ifdef __HADDOCK__ to test for Haddock and #if __HADDOCK__ == 202 to test for version 2.2.*

It would be more complicated than that: {{{ #ifdef HADDOCK #if HADDOCK >= 202 #if defined(GLASGOW_HASKELL) && GLASGOW_HASKELL > 610 -- (1) near normal code, with fewer haddock tricks (for haddock's ghc) #else -- (2) haddock tricks for new haddock, built with old ghc #endif #else -- (3) haddock tricks for old haddock #endif #else -- (4) normal code #endif }}} Assuming this is even approximately right, it looks rather complicated. Especially the bit about __GLASGOW_HASKELL__ inside __HADDOCK__ possibly referring to a different version than outside..

Yes, it becomes complicated. I don't think many people will compile with a different GHC version than Haddock's, though. Cabal disallows this currently, and doing it manually is a bit complicated since it will need the two GHC versions to both satisfy the dependencies of the package. Anyway, if a package author choses Cabal as the only way to build his package, he can safely assume that the GHC versions will never differ here.

Since the macro is not just needed during a Haddock invocation, but also during a normal compile, I think it should be defined by Cabal. Users of standalone-Haddock can always define symbols by passing GHC flags to Haddock.

GHC seems to define its own macros, and that might also be the preferred option for haddock, reducing the chance of inconsistencies.

I still think Cabal should define this macro, since it is needed not only by Haddock but also during normal compilations using GHC. Cabal is the build system here, so common macros should be defined there.

[waern]

Claus, since the headline of the ticket is a non-issue and the macro issue needs to be solved in Cabal, can I close this ticket?

[claus]

GHC seems to define its own macros, and that might also be the preferred option for haddock, reducing the chance of inconsistencies.

I still think Cabal should define this macro, since it is needed not only by Haddock but also during normal compilations using GHC. Cabal is the build system here, so common macros should be defined there.

I thought that was the whole point of that macro? *Only* haddock defines it, so nothing else sees any code guarded by it. Unless you want haddock to become a part of cabal, and cabal only, of course. And some folks still don't use cabal (darcs used to be an example).

If you don't think haddock should define its own macro, why not ask your users, on haskell-cafe?

Rename the ticket, or close it - just fix it first, please!-)

[waern]

Argh, I'm not sure what I was thinking there! Of course this macro should only be defined when invoking Haddock :)

I'm not totally convinced that the macro should be defined by Haddock, even though your argument about reducing inconsistencies is good. Haddock would have to turn on the preprocessor in addition to defining the macro for this to make sense. Do you propose that it should be turned on by default?

I think this should be fixed in Cabal, since I don't have a strong opinion on where this macro should be defined, and because it is already in Cabal.

[anonymous]

I thought the point was that for haddock 2 we did not need to define the __HADDOCK__ macro because haddock 2 understands GHC Haskell where as haddock 1 did not. Indeed it would not work if we defined __HADDOCK__ for haddock 2 because many people put non-Haskell in bits guarded by __HADDOCK__ because haddock 1 didn't understand things and didn't parse Haskell anyway.

Doing something like __HADDOCK__=2 would not work either, because old code does not look for that and would still present haddock 2 with bogus Haskell code.

Surely the right answer to these problems is to make sure haddock 2 does not fall over on the new syntax. It does not have to produce perfect documentation for them, just not fall over. If packages have to start adding conditionals for haddock 2 then they'll lose the benefits once haddock 2 does fully support the extended features.

[anonymous]

Replying to anonymous:

I thought the point was that for haddock 2 we did not need to define the __HADDOCK__ macro because haddock 2 understands GHC Haskell where as haddock 1 did not. Indeed it would not work if we defined __HADDOCK__ for haddock 2 because many people put non-Haskell in bits guarded by __HADDOCK__ because haddock 1 didn't understand things and didn't parse Haskell anyway. Doing something like __HADDOCK__=2 would not work either, because old code does not look for that and would still present haddock 2 with bogus Haskell code. Surely the right answer to these problems is to make sure haddock 2 does not fall over on the new syntax. It does not have to produce perfect documentation for them, just not fall over. If packages have to start adding conditionals for haddock 2 then they'll lose the benefits once haddock 2 does fully support the extended features.

I was assuming that under the proposal we were discussing that old code that use the HADDOCK macro to turn on code that doesn't compile was to be considered broken (i.e. we assume everyone is using Haddock 2.* and have fixed their code). Anyway, as you say, one option is to avoid having the macro at all, since the cases when you need a macro like this to avoid crashes should become zero, eventually.

You might still want such a macro to support multiple versions of Haddock (to #ifdef around use of new features), but it would probably be acceptable to just require the latest version of Haddock instead. Especially since clients of your package that can't install the latest Haddock only loose the ability to install the documentation of your package. They can still build it.

[claus]

One more item to consider: some code not only uses __HADDOCK__ to prevent haddock from falling over, but also to help it along, producing more accurate documentation.

It might well be that haddock2 doesn't need any such help, but if you want to drop __HADDOCK__ for haddock2, you would want to be sure that the generated documentation doesn't suffer, right?

Some examples:

- instance inference workarounds in OpenGL&co (should no longer be needed?)

- data type presentation (eg, in base/GHC/Base.lhs)

- import adjustments (eg, in base/Foreign/Marshall/Error.hs, or in OpenGL/Graphics/Rendering/OpenGL/GL/Framebuffer.hs, OpenGL/Graphics/Rendering/OpenGL/GL/Rectangles.hs)

[waern]

For now, we decide not to define HADDOCK. Claus use-case can be solved by waiting for the new Haddock version and then depending on that. If you really want HADDOCK you can define it yourself in your build system, or use Cabal which defines it for you. If a use-case comes up where this macro is needed for something else than avoiding syntax not yet supported by Haddock, we could perhaps re-consider (though such a case may go unnoticed due to Cabal defining HADDOCK).