Including an image using roxygen documentation

Question

Is it possible to include an image in documentation generated by roxygen? I have a number of functions that are essentially wrappers for ggplot() that I'd like to document by showing an example of the output.

Hackle

If I could find it, I wouldn't have asked. The only comprehensive list of syntax that I could find was at bioconducter... and it didn't include syntax for including an image. – Hackle

And also in "Writing R Extentions". – Hackle

I think it's only in 2.14 which is probably why you can't find it. – Aerodyne

Very old blog post by Romain Francois describing what to do: romainfrancois.blog.free.fr/index.php?post/2010/04/03/… (but this seems to require a developmental branch - I can't get this to work myself) – Valenta

Romain's method is a bit of a hack. There's an officially supported method coming soon in 2.14 – Aerodyne

@Aerodyne where did you find that out? (link?) – Hackle

Answer 1

As per the change list from the announcement of R 2.14:

Rd markup has a new \figure tag so that figures can be included in help pages when converted to HTML or LaTeX. There are examples on the help pages for par() and points().

From: http://cran.r-project.org/doc/manuals/R-exts.html#Figures

To include figures in help pages, use the \figure markup. There are three forms.

The two commonly used simple forms are \figure{filename} and \figure{filename}{alternate text}. This will include a copy of the figure in either HTML or LaTeX output. In text output, the alternate text will be displayed instead. (When the second argument is omitted, the filename will be used.) Both the filename and the alternate text will be parsed verbatim, and should not include special characters that are significant in HTML or LaTeX.

The expert form is \figure{filename}{options: string}. (The word ‘options:’ must be typed exactly as shown and followed by at least one space.) In this form, the string is copied into the HTML img tag as attributes following the src attribute, or into the second argument of the \Figure macro in LaTeX, which by default is used as options to an \includegraphics call. As it is unlikely that any single string would suffice for both display modes, the expert form would normally be wrapped in conditionals. It is up to the author to make sure that legal HTML/LaTeX is used. For example, to include a logo in both HTML (using the simple form) and LaTeX (using the expert form), the following could be used:

 \if{html}{\figure{logo.jpg}{Our logo}}
 \if{latex}{\figure{logo.jpg}{options: width=0.5in}}

The files containing the figures should be stored in the directory man/figures. Files with extensions .jpg, .pdf, .png and .svg from that directory will be copied to the help/figures directory at install time. (Figures in PDF format will not display in most HTML browsers, but might be the best choice in reference manuals.) Specify the filename relative to man/figures in the \figure directive.

Hackle

How can I include mutiple options? – Corposant