[Haskell-cafe] ANNOUNCE: Haddock version 2.8.0 -> HTML vs. XHTML

[Christopher Done]

On 6 September 2010 17:11, Mark Lentczner <markl at glyphic.com> wrote:
> On Sep 6, 2010, at 2:40 AM, Henning Thielemann wrote:
>> ... focusing on a small set of assumed popular browsers ...
>
> I didn't want to assume either. I ran a survey of the Haskell community and got over a 150 responses.

> On Sep 6, 2010, at 2:40 AM, Henning Thielemann wrote:
>> and complying to their quirks is the wrong way.
>
> I believe the only sop to browser quirks in the current Haddock output are three lines of CSS that came from YUI 3: CSS Fonts [2] to achieve consistent font sizing in IE. These are well researched and minimal.

Speaking as someone who worked at a company where we had to write 100%
valid XHTML and CSS for *non-trival* designs (groans at the
recollection), generally for fairly simple documents you can write
standard compliant web pages with (X)HTML/CSS/JavaScript and it will
render the same on Firefox/Chrome/Safari/Opera/IE8. It will probably
work but look less fancy on IE6 if it's simple. If other browsers
don't render correctly, that's not your problem. Regarding font
sizing, you shouldn't really have to care about the size of the font.
If your page renders differently on different browsers due to
different font settings, that's because the user/browser chose that
font set. Why do you care about consistent font sizes?

Personally I'm pragmatic, I don't care about W3C validation, I do care
about standards and accessibility. If your page is semantic,
usable/accessible across the major browsers then you've done a great
job and W3C validation is just a pat on the back. I think it's a
matter of priorities. If we're going to appeal to authority, Google
see it fit to start using HTML5 straight away (and they really care
about validity) and (I was told at the Zurich Google offices by
someone who works on YouTube) that we have no business sending XHTML
to web browsers. But I don't see the particular mark-up as a Big Deal
like others do, when (as I demonstrate below) there are more important
issues to deal with that most people don't get right.

> As I did the work on Haddock, I tested the results on five browser/os combinations on my own machines, and about 30 browser/os combinations via browsershots[1].

FWIW there's a great web site that provides screenshots of IE
immediately: http://ipinfo.info/netrenderer/ Don't waste your time on
obscure browsers. You have better things to be doing.

> There were a few times where I tried something (usually a choice of markup and CSS) that looked nice in WebKit browsers (Safari and Chrome), but didn't work in Firefox or others. In those cases I retreated to other approaches. A notable example is the "Portability" box in the upper right. I wanted that to be a dl list, and could get it to style nicely in all browsers except Firefox on Linux! I retreated to a table in that case. Since both the thing I tried and the result were valid markup and CSS, I'm hoping you won't consider this a major concession to "quirks".

I'd like to see such cases of inconsistency between Webkit and Firefox
("on Linux"), I can help out if you're having trouble. You want to do
the portability box as a definition list? For semantic meaning and
search engines, there should be one h1 in the page, many h2's, and
subheadings, etc. A really easy way to check your site's quality as a
structured document is by rendering it without CSS or JavaScript,
because it can make you aware of problems immediately:

http://i.imgur.com/7ksCW.png

There's no h1, what's the title of this page? The h2s have been
written as h1's, and the contents, title and description aren't
headings at all. The portability table is done with tds (table *data*)
with no th's (table *heading*) and there's no actual description for
the table. Headings are useful for navigating the document -- this is
how blind people work in a browser, they get a list of headings and
tab through it quickly (I have a reference study for this, I'll find
it if you're interested). Just think about what are the main points of
this document and the way to code it comes naturally. Like I said,
you're priority has been cross-platform and validation but basic
things like semantic document structure have been overlooked.

Anyway, I think you're doing a sterling job and you seem to really
care about doing it right, good job! It looks really nice, gives a
professional sheen to Haskell's documentation. I know you need to
build up a thick skin to deal with all the bikeshed-like criticism
that always seems to crop up when web sites are discussed. Don't worry
about my criticisms, I'm constructive about it! If you care about this
stuff then I'll put my money where my mouth is and send some patches
to address whatever I think could be improved, you don't have to lift
a finger. If you're not really bothered then disregard all my above
comments and just imagine I said "awesome design, good job!"