[Haskell-cafe] Re: Haddock GSoC project

[Isaac Dupree]

Simon Marlow wrote:
> Obviously I think these tickets are important, since I wrote them :-)  In
> terms of priority, I think #1567 is at the top: not having this harms our
> ability to reorganise and abstract things, it puts an arbitrary barrier
> between packages.  It's possible my perspective is slightly skewed though,
> since most of the packages that are affected by this are in GHC's core
> package collection.

still,
-reorganization happens in others' packages too, and we want to encourage 
this!
-everyone uses GHC's core packages and complains when the documentation is 
broken (and unfixable!) :-)

but sure, we should find out if other people have higher priorities elsewhere. 
(cafe citizens and hackers, tell us what you think!)

> #1568 is just refactoring, but it's a high priority: we need to get this
> code out of GHC and back into Haddock.  This is important for Haddock's
> long term future and general maintainability, though it won't have any
> visible effect on the way Haddock works.

yes, I agree, things will keep being a little unpleasant until we do this.  My 
intuition says that with 2-3 months I should have time to do this refactoring 
too, but then, I haven't actually spent a week figuring out just how difficult it 
is :-).  Probably needs some refactoring the data-types that GHC emits 
comments as, and then possibly-more-complicated having Haddock parse and 
structure the Haddock-syntax within the comments (and as it relates to the 
actual code!)

> The index page really isn't working right now, since we added the
> search-box functionality it has become unusable for the GHC library docs
> (small libraries are ok).  Thank goodness we have Hoogle and Hayoo.  We
> should really just revert to the old A-Z links, I'm not sure if there's a
> Haddock ticket for this.

maybe http://trac.haskell.org/haddock/ticket/70 is related?

> There's lot of other stuff that could be done.  For instance I'd really
> like someone with some CSS expertise to have another go at Haddock's HTML
> layout.

I've done some manual HTML/CSS on my own website (W3C validated!)... don't 
know if it comes anywhere near "expertise" though :-)

One random haddock problem I remember bothering me recently is: no "view 
source" link on each instance in the list of instances for a data-type (so I 
clicked a nearby "view source" and scrolled to find the instance source, which 
was in the same module)

-Isaac