CSS Themes

[Simon Marlow]

On 21/07/2010 07:13, Mark Lentczner wrote:
>> I don't think so. I initially proposed we make it so to make
>> launching it easier but perhaps it'll be more fun to launch it with
>> a user-visible change. Lets try to work out a style together, I
>> suggest we base it on Thomas style, and polish up all the pages and
>> launch it!
> Well..... I am of two minds on this:
>
> On the one hand, we'd like to remove any possibility of lots of
> grumbling about "going back to the old Haddock 'cause it looked
> better", or drive to keep the old HTML backend in the code base to
> appease people who want "that good ol'Haddock blue tables look". I
> really want to remove that HTML backend: I hate moldy code!
>
> On the other hand, I realize that what we ship as default will be the
> "look" of Haskell code - and having it look as best as we can make it
> is a good thing. Of course, "best" is subjective, and, well, people
> will have to entrust our subjective taste here.
>
> This brings me to a bigger discussion that promised about how to
> handle CSS themes. Here are some non-exclusive thoughts on the
> matter:
>
> 1) 99% of developers are just going to go with what Haddock does "out
> of the box". If the default theme is Classic, that is what they'll
> do. If the default theme is something else, they'll do that.
>
> 2) If we include a style switcher by default and include several
> distinct looking themes by default, then some percentage (20%?) will
> explore them and pick one they like. On Hackage and their home
> computer, the choice should "stick" (the code uses a cookie to save
> the users' choice per site.) People will still see the default theme
> whenever they browse doc elsewhere for the first time - and they may
> well never take the effort to switch it on other sites.
>
> 3) Some projects, like Snap, will choose to publish their doc on
> their own site rather than depend on Hackage. These projects will
> probably want to pick a single theme and "enforce" it by not having
> the Style menu show up, since they will want it to integrate to the
> rest of the site's look. There is a good chance these projects will
> write a custom theme for such use.
>
> 4) It might be nice to ship initially with Classic by default, but
> offer several, rather distinct, themes so that we can let the
> community pick the one they like the best. Then, say three months
> down the line, switch the popular voted theme as the default.
>
> 5) It might be nice to ship initially with something wholly new and
> really wow the community!
>
> So, this leads me to ponder two questions:
>
> A) How important is it to develop the Style switcher? 1, 3, and 5
> point to it being a minor feature - perhaps used primarily by theme
> creators. 2 and 4 suggest we fully develop to enable user choice.
>
> B) How open will the community be to our designing the new look of
> Haskell documentation?
>
> Thoughts?

I vote for:

  * Work on a really nice theme that we all pretty much agree on.
    Right now, Thomas's is looking like the front runner to me.

  * Make this the default Haddock style.

  * Don't include a style switcher in the generated Haddock, at
    least by default.  It's a knob that most people don't need,
    and we should focus on doing one thing really well; delegating
    choice to the user is a cop-out.

  * Nevertheless, make it easy to switch styles for developers
    who want to style their own API documentation.

So to answer your Qs directly:

  A) not terribly important, make it an optional feature
  B) I don't think this will a problem.  If you're worried then
     you could have a beta phase and ask for comments, but that's
     likely to lead to a huge thread on haskell-cafe with low
     SNR.  There are enough people involved in this effort
     with the skills to produce a great result, so let's just
     do it.

Cheers,
	Simon