[R] Improving help in R

[Hadley Wickham]

> One difficulty in getting the help pages to look beautiful is that the
> original input is so inconsistent, and package authors (naturally) get upset
> when CRAN starts rejecting packages because of errors that used to be
> ignored.  The current output is definitely a compromise aimed at making most
> packages work.
>
> However, this doesn't stop us from using a different style sheet. It would
> be very easy to have the system generate pages with markup that allowed a
> user to customize fonts, colours, etc.  The main difficulty here is that R
> users use lots of different systems and lots of different browsers, so it
> takes some work to find displays that work everywhere. (For example, someone
> mentioned drop caps in your display, but I don't see those in Firefox on
> Windows -- presumably I don't have the font you specified.)
>
> BTW, when you say "some parser could probably parse the existing help
> files", it sounds as though you are unaware of the fact that the help source
> is in Rd format, and it is parsed into various output formats. You can see
> the parser in tools::parse_Rd, and the formatter in tools::Rd2HTML.

And the great thing about those tools is that it's fairly easy to
convert Rd files into alternative help files. I've recently been
working on staticdocs (https://github.com/hadley/staticdocs) which
aims to convert Rd files into html particularly well suited for
distribution on standalone websites.  You can see the what the output
looks when applied to the ggplot2 package at
http://had.co.nz/ggplot2/docs/.

It's made possible by:

* Duncan's Rd parser
* twitter's bootstrap framework for html/css
* Romain Francois' highlight package (for syntax highlighting R code)
* Edwin de Jonge's whisker (for html templates)
* Barrett Schloerke's helpr package (which provided most of the initial code)

Hadley

-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/