The new help system that was introduced in R 2.10.0 and documented in an article of the R journal is very promising.

One thing that is planned for future versions of R (maybe 2.12.0) is some way to include images into Rd documents using the fig option of the Sexpr macro

Another way is to use data uri and embed the image directly inside the html code, so this morning I played with this and wrapped up this little c library into an R package called base64 and hosted in the Rcpp project at r-forge.

The package allows encoding and decoding files using the Base64 format. It currently has three functions: encode, decode and img. encode and decode do what their name implies, and img produces the html code suitable for embedding the image into an html document.

The help page for img actually contains an image, here is it:

and here is how it is produced:

\details{
\if{html}{
    The following graph is embedded in the document using the \code{img} function   
    
\Sexpr[stage=render,results=rd,echo=FALSE]{
    library( base64 )
    library( grDevices )
    library( graphics )
    library( stats )
    
    pngfile