[haskell-platform] #176: Extensive Haddock breakage

[haskell-platform]

#176: Extensive Haddock breakage
------------------------------+---------------------------------------------
 Reporter:  Orphi             |       Owner:     
     Type:  defect            |      Status:  new
 Priority:  critical          |   Milestone:     
Component:  (none-specified)  |    Keywords:     
------------------------------+---------------------------------------------
 Documentation problems have been a recurring problem for Windows binary
 installers since I first started using Haskell, way back in the days of
 GHC 6.6. It seems that the Haskell Platform is continuing the tradition of
 broken documentation.

 I have conducted a fairly exhaustive examination of HP 2011.2.0.0 (and I
 believe HP 2011.2.0.1 is broken in almost exactly the same ways). I will
 now document the breakage I have found.

 After installing HP, all the Haddock documentation for the installed
 packages gets put in a big documentation folder. This contains an index
 page listing everything that's installed, plus a folder for every
 installed package which contains the documentation for that package. (And
 of course, the index page links into these sub-folders.)

 Unfortunately, only about 50% of the packages that come with HP are
 actually listed on the index, and a slightly different 50% of them have
 documentation folders.

 What follows is a comprehensive list of all the packages broken in HP
 2011.2.0.0; for HP 2011.2.0.1, the list appears to be nearly identical,
 with a few tiny differences.

  * GLUT (no index entry, no doc folder)
  * HTTP (no index entry, no doc folder)
  * HUnit (no index entry, no doc folder)
  * OpenGL (no index entry, no doc folder)
  * QuickCheck (no index entry, no doc folder)
  * bin-package-db (doc folder is present, but no index entry)
  * cgi (no index entry, no doc folder)
  * deepseq (no index entry, no doc folder)
  * fgl (no index entry, no doc folder)
  * haskell-src (no index entry, no doc folder)
  * html (no index entry, no doc folder)
  * integer-gmp (doc folder present, but no index entry)
  * mtl (listed in the index, but no doc folder present)
  * network (no index entry, no doc folder)
  * parallel (no index entry, no doc folder)
  * parsec (no index entry, no doc folder)
  * regex-base, regex-posix, regex-compat (no index entry, no doc folder)
  * stm (no index entry, no doc folder)
  * syb (no index entry, no doc folder)
  * text (no index entry, no doc folder)
  * time (doc folder present, but no index entry)
  * transformers (no index entry, no doc folder)
  * xhtml (listed in the index, but no doc folder)
  * zlib (no index entry, no doc folder)
  * utf8-string (listed in the index, but no doc folder, ghc-pkg claims
 it's not installed, and I can't see any lib files for it)
  * haskeline (listed in the index, but no doc folder, ghc-pkg claims it's
 not installed, and I can't see any lib files for it)

 In short, the Haddock index has 50% of its content missing, several
 modules have broken hyperlinks, and there's a couple of packages listed
 which aren't even in HP!

 I haven't performed an exhaustive check of HP 2011.2.0.1, but the list of
 doc folders that do and don't exist is almost identical to HP 2011.2.0.0,
 so we can safely assume the problem still exists.

 Proper documentation is utterly critical. I'm fed with of the Haskell
 binary installers for Windows giving me half broken documentation! I've
 been filing Trac tickets about this since the days of GHC 6.6. Can we
 please, please, pretty please with idempotent automorphisms on top, PLEASE
 get this fixed??

 (I would also suggest some way of automatically testing that this stuff is
 working correctly would be merited.)

-- 
Ticket URL: <http://trac.haskell.org/haskell-platform/ticket/176>
haskell-platform <http://trac.haskell.org/haskell-platform>
The Haskell Platform: a comprehensive and robust collection of Haskell libraries