Including images in R-package documentation (.Rd) files

Question

I am working to document a visualization function in a package of mine. For this purpose I would like to have an image embedded through the Rd-file 'funcname.Rd' that could explain various parameters utilized in the function, and which would pop up if user goes to read the package manual PDF or writes '?funcname' in R. Something in the lines of:

'Writing R extensions'-document doesn't seem to address this issue, and the only references I could find were this blog post and this R-devel discussion. The former has a broken link to a package called 'base64' and the latter only addresses various alternatives like including the images in R package vignettes instead. It would be great if this could be CRAN-compatible.

Any advice on how to approach this issue would be appreciated, thanks!

Boony

It must be possible to process your Rd-file into plain text. I'd probably prefer to include code that produces such a figure in the examples. – Sharpe

This is approximately one of the work-arounds they suggested in the R-devel discussion; apparently using 'example(funcname)' is something people have used. The thing with R-produced figures is that I wanted to have several stylized lines, curly brackets, etc in the figure to point out what different parameters did, and doing this just in R can be rather inconvenient. But you are correct. – Boony

Just be aware that some (many?) users won't see the figure. E.g., if they work from a command line. – Sharpe

Answer 1

Untested, but look at the R source on GitHub, it would appear they add an image to ?par documentation file in the following manner:

 \item{\code{mai}}{A numerical vector of the form \code{c(bottom,
        left, top, right)} which gives the margin size specified in
      inches.\cr
      \if{html}{\figure{mai.png}{options: width="35\%" alt="Figure: mai.png"}}
      \if{latex}{\figure{mai.pdf}{options: width=7cm}}
    }

The figure appears to be saved in /man/figures.

For more details see the Writing R Extensions section on the topic.

Nagy

This seems to be at the moment the best way, answer accepted. For my purpose it works well, but like Roland pointed out in his comments above, one should not expect all users to see the figures. – Boony

Just an FYI for anyone happening upon this question in the future. The syntax specified above works well! – Sandry