On 09/03/2014 01:00 AM, Ivan Lazar Miljenovic wrote:

On 3 September 2014 07:16, Mateusz Kowalczyk wrote:

...

On 08/31/2014 02:50 PM, Mateusz Kowalczyk wrote:

...

Hello,

I'd like to announce the release of Haddock 2.15.0.

[snip]

Thanks!

[1]: https://github.com/haskell/haddock/issues

Oops, something I forgot to mention:

1. {-# OPTIONS_HADDOCK show-extensions #-} will probably become the default from next release. Of course you'll be able to switch it off if you don't like it but you'll have to do so explicitly.

If this is the case, will there be any way of documenting why a potentially "scary" extension (e.g. UndecidableInstances) is being used?

No official way and no plan to ever support documenting extensions: adding the code to the GHC lexer and extracting it back out of the API is a lot of work. Trying to decide how the show it in the documentation is probably equally as hard. If someone *really* thinks they need this, I'll be happy to review their patch for the whole thing ;). I don't actually know of anyone ever asking for such a thing (yet!). Personally I recommend using either the module header to say why the extension is used or documenting your class/instance. Header is probably better for consistency if you do this a lot and in the HTML it appears near the box that houses the extension list.

...

2. We will remove ‘frames’ unless someone want to step up and fix the two issues related to them: #114 and #274. Hackage strips the link out from the JavaScript we ship so barely anyone knows or uses them but if you uploaded your own docs then you'll have them. If you like them then please step up to fix them or they will have to go.

Thanks!

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

-- Mateusz K.

On 09/07/2014 09:10 AM, Joachim Breitner wrote:

Hi,

Am Sonntag, den 31.08.2014, 14:50 +0100 schrieb Mateusz Kowalczyk:

...

I'd like to announce the release of Haddock 2.15.0.

Cool.

How compatible are the .haddock files?

If you're coming from 2.14.3 then there is no problem. I think the last change was at 2.14.0 so if you're on then you should be good to update. If you're on 2.13.x or earlier then you'll have to regenerate all the docs but IIRC the GHC versions that 2.13 and 2.14/15 are compatible with are different anyway so you can't have both co-existing. You can check what your current cversion is at through haddock --compatible-interface-versions although that flag has been a fairly recent addition (2.14.0). For 2.14.0-2.15.0 it is version ‘25’.

In particular, and not only related to this upgrade: Under what condition can Debian upgrade haddock (resp. haddock-api resp. haddock-library) so that the .haddock files generated by the compiler build, using the haddock version that was shipped with GHC, can still be used?

tl;dr: as long as the interface doesn't change but when that actually happens, depends. Personally I try to time this with a GHC release so that people don't tend to notice as you normally don't mix the files generated by different versions. cheat sheet: GHC 7.6.3 -> 7.8.3, no good, interface changed 2.14.0 ->* 2.15.0, all good, same interface 2.15.0 ->* future, no idea! At the moment I think we don't have any changes in plans. If GHC 7.10 doesn't result in some big changes or we don't have new, breaking features then it well may be possible that Haddock 2.16 or whatever it will be at next GHC will be compatible with 7.8.2/7.8.3/7.10.x through some CPP on our end to account for API changes. If it adds new structures and stuff we need to store information about (PatternSynonyms are an example of a thing that we'd need to store info about but that wasn't around for 7.6.3) then we have to bump it. It may well be that we could improve the way we store the interfaces, such as store GHC version too and read that off so we know what we're working with. This could make it a bit more future-proof but it'd be difficult to maintain. Ironically, such a change would itself result in an interface version bump. Long-winded answer: First a brief overview. ‘haddock’ is now simply a Main module over ‘haddock-api’, I think the updates to ‘haddock’ in the future will simply be bumping the ‘haddock-api’ version in its cabal file so that it's easy to keep track. ‘haddock-api’ is where the bulk of the work is, all the nasty ‘talk to GHC’ stuff and serialisation. This depends on ‘haddock-library’ which means that if ‘haddock-library’ has breaking changes then ‘haddock-api’ has to be updated too. ‘haddock-library’ is the bits that don't need GHC, currently only the parser but hopefully more in the future. Ideally you want to use the latest version of each together with each other but you can freely update ‘haddock-library’ as long as it didn't have breaking changes. Currently ‘haddock-api’ has 1.1.1.* constraint. and it should work with all matching versions. In summary, if ‘haddock’ updates, you want to update ‘haddock-api’ too. If ‘haddock-library’ makes a minor release, you can (but don't have to) update it on its own. If it makes a breaking release then ‘haddock-api’ will be updated too. We'll basically make sure that the latest ‘haddock-api’ compiles with its ‘haddock-library’ constraint. Now to try and answer your question: it's fairly easy to find out if you're compatible simply with --compatible-interface-versions. We update either when: 1. there was new markup 2. there was a GHC change that results in different binary format So far I have not seen 2. happen yet but if it does happen, it will be at new GHC release, changing this CPP: binaryInterfaceVersion :: Word16 #if __GLASGOW_HASKELL__ == 708 binaryInterfaceVersion = 25 binaryInterfaceVersionCompatibility :: [Word16] binaryInterfaceVersionCompatibility = [binaryInterfaceVersion] #else #error Unsupported GHC version #endif The 1. point doesn't happen often but it does happen, such as when I added the new syntax for headers or bold; another example was when I wanted to store language extensions used in the module. This was coordinated with 7.8.x release so that most people wouldn't have noticed there was interface change.

Greetings, Joacihm

-- Mateusz K.