Stop! Tickets are now managed at GitHub.

Please enter new tickets, and find and edit existing tickets there:


Ticket #176 (closed defect: fixed)

Opened 3 years ago

Last modified 21 months ago

Extensive Haddock breakage

Reported by: Orphi Owned by: refold
Priority: minor Milestone:
Component: Windows installer Keywords:
Cc:

Description

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.)

Change History

Changed 3 years ago by refold

  • owner set to refold
  • status changed from new to assigned

This is a known problem, I hope to fix this for the next release. In the meantime, there is always Hoogle.

Changed 3 years ago by Orphi

OK. Well so long as somebody knows about it and is working on fixing it. If this does get fixed for the next release, that would make me very happy.

Changed 3 years ago by refold

  • component changed from (none-specified) to Windows installer

Changed 22 months ago by MtnViewMark

  • status changed from assigned to new

Is this resolved?

Changed 22 months ago by refold

  • priority changed from critical to minor
  • status changed from new to assigned

Yes, mostly. There were some problems with OpenGL documentation that I didn't have time to look into.

Changed 21 months ago by refold

Probably better to close this and create a separate ticket for the OpenGL documentation problems.

Changed 21 months ago by refold

  • status changed from assigned to closed
  • resolution set to fixed

Closing in favor of #213.

Note: See TracTickets for help on using tickets.