[Haskell-cafe] Haddock Markup

[Richard O'Keefe]

On 10 Feb 2009, at 1:19 am, Wolfgang Jeltsch wrote:
> This is only true if your destination format is PDF, DVI or PS. For  
> a webpage,
> you’ll need MathML in the end and TeX is not so good in producing  
> MathML, I
> suppose.

Hmm.  I find designed-for-HTML documentation horrible.
In many ways the current Haddock output is the worst
of both worlds:  it is inconvenient for on-screen viewing
and doesn't exploit paper very well either.

Amongst other things, people who are learning a library
package need overviews, examples, conceptual models, all
sorts of details, whereas people who already know them
mainly need reminders, for which web pages are well suited.

I would point out that you DON'T need MathML for a web page,
because a PDF document can *be* a web page.  You can link to
one, you can display it in your browser, and it may contain
links to other pages.

Especially if one can download a tolerably full snapshot of
the library and all its documentation, updating this at rare
intervals, PDF-on-the-local-host suits me much better than
HTML-on-the-Web.