[Haskell-cafe] Red links in the new haskell theme

[Mark Lentczner]

Some notes on the Haddock re-design:

1) HTML supports the concept of alternate style sheets. If present, then the idea was that browsers would give the user the choice, somewhere, to choose among them. While Firefox does this (View > Page Style), and I'm told that Opera (View > Style), and Konqueror (View > Use StyleSheet) do, the other big-name browsers, IE, Safari, Chrome, do not.

Since support is so lacking, the common thing to do, and what I implemented for Haddock, is to use Javascript to pull the alternate style sheet information out of the page and build a menu that is then placed back into the page. This is the "Style" menu in the top right of the page. If you have Javascript turned off, it won't appear as it is not part of the markup.

The cookie, which is set from Javascript is so that you don't to re-pick the style on every page load. I'm assuming that those browsers that do implement a style sheet menu remember this per-site, but I don't know. It is a limitation of cookies that it can only remember your choice per-site.


2) What styles appear depend on what was specified when Haddock was run to produce the pages. By default it includes just the new Ocean theme. If --default-themes is specified (as it is on Hackage), then both Ocean and Classic are included. You can build your own themes and include them with --theme, alone or in combination with the built-in themes.

If the resulting theme set is a singleton, then no "Style" menu will appear on the page.


3) Without really doing a tracking analysis (preferably by tracking eye movements, or at least mouse movements, and in all cases recording accurate view times and location of clicks), it isn't possible to optimize a web page down to the level of which menu links should be in in which order, or other such small changes. That isn't saying such changes won't have a big impact, only that it is hard to reason about them because the tracking results are often non-intuitive. In the absence of such things, all one can do is bring one's experience and design skills to bear.


4) While Haddock tries to minimize the use of Javascript, it still has some. There is a tension between wanting to produce pages that can be printed documentation, and creating a effective on-line reference. Between the theming ability, and the new LaTeX backend, it is now possible to achieve these two aims with separate Haddock outputs.

In modern browsers, Javascript is very efficient and even moderate amounts of Javascript can be crafted to not affect load times. Haddock still has an issue here that the Javascript is repeated in every directory, thus ruining caching. When this is fixed, we'll be able to use more Javascript, which will enable us to make the reference easier and faster to navigate.[1]


5) It does not make sense for users to configure colors or fonts for web sites any more than it would for magazines or books. Effective presentation of information requires design including choice of fonts, colors, graphics and layout - and these vary by the information and intent of the content. There is no choice a user an make that works best for all.

It is important for accessibility that those users that need to can override fonts and colors. All modern browsers allow this, and one of the major aims of the Haddock redesign was to output clean markup so that it worked in such situations, as well as with screen readers. In other words - if you want to override the fonts and colors you can now do so effectively.


6) Over the Summer the new style was made available on the web for people to look out for several months, and at one point I conducted a poll. In that poll only 81% preferred the newer look, and only 11% preferred the older.


  - Mark "Haddock web scullion" Lentczner


[1] An example of an HTML reference work that is highly usable and uses plenty of Javascript (>700k!) to achieve it, yet works very well: http://developer.android.com/reference/packages.html