[Haskell-cafe] ANNOUNCE: Haddock version 2.8.0

[John Millikin]

On Thu, Sep 2, 2010 at 21:14, Mark Lentczner <markl at glyphic.com> wrote:
> I choose to switch Haddock's output from HTML to XHTML mostly because I have found the consistency of rendering cross-browser to be greater and easier to achieve with XHTML. I'm not alone in this opinion: Many well respected web design authorities have promoted, and publish their own sites, in XHTML.[1] Even Microsoft's own developer web site uses it[2]!

You're not generating anything browsers will parse as XHTML, so I find
it unlikely that attaching the correct doctype will cause problems. I
am extremely skeptical that using an HTML4 doctype will render
incorrectly when an unrecognized doctype works as expected across all
browsers.

> [1] See, for example:
>        http://www.alistapart.com/
>        http://www.csszengarden.com/
>        http://www.quirksmode.org/
>        http://happycog.com/
>        http://www.w3.org/
>
>        all of which are published as XHTML
>
> [2] See: http://msdn.microsoft.com/en-us/default.aspx

Browsers treat any data sent using the "text/html" MIME-type as HTML.
Those pages are being served as HTML, so browsers treat them as HTML
with an unknown doctype. In particular, CSS and JS behavior on these
sites will be that of HTML, *not* XHTML.

Firefox will show you how the page is being rendered (HTML or XHTML)
in the "page info" dialog. I don't know of any similar feature in
Chrome.

> [5] I can't find any evidence for your assertion that Internet Explorer doesn't support XHTML, or the way Haddock names the files (and hence URLs).

IE versions 8 and below (I've not tested IE9) will not render XHTML --
they pop up a "save as" dialog box. You're welcome to verify this by
opening an XHTML page (such as < http://ianen.org/haskell/dbus/ >) in
IE. You may be confused, because the pages you mentioned earlier *are*
rendering in IE. However, they are not being rendered as XHTML --
again, browsers are rendering them as HTML with an unrecognized
doctype.

Haddock is generating files with an .html extension, which causes
webservers to serve it using "text/html", the incorrect MIME-type. The
correct extension for XHTML content is .xhtml.

For some reason, it is common to use XHTML doctypes in HTML documents
-- I assume because people think the "X" makes it more modern.
However, this is incorrect behavior. It is better to serve a page
correctly as HTML4 than incorrectly as tag soup.