#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
_______________________________________________
Haskell-platform mailing list
Haskell-platform@projects.haskell.org
http://projects.haskell.org/cgi-bin/mailman/listinfo/haskell-platform
