How to document man/*.Rd pages with images?
Hi, On Wed, May 11, 2011 at 3:42 PM, Sean Robert McGuffee
<sean.mcguffee at gmail.com> wrote:
On 5/11/11 3:13 PM, "Dan Tenenbaum" <dtenenba at fhcrc.org> wrote:
On Wed, May 11, 2011 at 12:08 PM, Sean Robert McGuffee <sean.mcguffee at gmail.com> wrote:
Hi, I?m trying to figure out how to put images into my package?s help documentation. I?ve gotten to the point where I can put the images in the /inst/doc/ directory. I have also gotten to the point where I have package checks without any warnings. I couldn?t find the terms ?picture,? ?image,? or ?graphic? in a text search within the Writing R Extensions: 2 Writing R documentation files <http://cran.r-project.org/doc/manuals/R-exts.html#Writing-R-documentation-f iles> I tried a couple of LaTeX guesses, but they lead to the following errors on check: Warning: /LAB/SRM/PROGS/R_PACKAGES/Ralign/man/Ralign139.Rd:3: unexpected UNKNOWN '\usepackage' Warning: /LAB/SRM/PROGS/R_PACKAGES/Ralign/man/Ralign139.Rd:36: unknown macro '\includegraphics' What is the right way to do this? Thanks, Sean
Given a graphics file called foo.png, you can include it in a vignette
as follows:
\includegraphics[width=0.5\textwidth]{foo}
I've tried adding this in a man/*.Rd file, but I get the following warning:
Warning: /LAB/SRM/PROGS/R_PACKAGES/Ralign/man/Ralign139.Rd:16: unknown macro
'\includegraphics'
In particular, I put
\includegraphics{../doc/Sean.jpg}
inside a \details{} section.
It seems that the term "vignette" may somehow be different than the man/*.Rd
files. As is somewhat typical of the R documentation, there is a whole
section on 1.4 Writing package vignettes without a definition of "vignette"
as far as I can tell.
Think of vignettes as "tutorials" you include in your package to show how consumers of your package can use it in different ways .. something like an advertisement of how cool your package really is, which is a bit harder for a user to appreciate by just browsing a list of function documentation (which the *.Rd files generate). As you are suspecting, they are indeed different than the help files that pop up via the ?myFunction route.
I want to clarify that I'm trying to put the images in a file that will come up when I type ??myPackageName or library(myPackageName);help(myPackageName).
I actually don't believe you can do this.
I'm not sure if that's the same as a vignette or not,
They are not the same. A good source to learn more about what you might use vignettes for are the bioconductor packages. All bioconductor packages are required (strongly encouraged(?)) to include vignettes. For example, look at their ShortRead package: http://www.bioconductor.org/packages/release/bioc/html/ShortRead.html In the "Documentation" section, you will find two vignettes there, both of which include pictures embedded in them. I can see how including pics in the function documentation can also be helpful. An alternative is to have the pictures that you would include in these files be generated by the code in the "Examples" section of your function documentation, so that the user can do: R> example(yourFunction) And have R produce the plots "live".
[some quote grooming] I literally have everything I need working in man/*.Rd files except image references. Do I have to learn about vignettes now after all that work to get the man/*.Rd files going?
Only if you want to embed images in some type of documentation. They're more or less ordinary LaTeX files that you can embed R code into. Very handy to know how to use, actually, even outside of the "Package Authoring" context, so ... perhaps you can consider it as good exercise if you decide to take it on :-) But again, you can always go the other route I proposed, which is to have your Example code generate these plots on the fly. In hopes of saving you some time, to go the "Example route," it is often helpful to include a small example dataset in your package that your Example code can load and work off of. Hope that helps, -steve
Steve Lianoglou Graduate Student: Computational Systems Biology ?| Memorial Sloan-Kettering Cancer Center ?| Weill Medical College of Cornell University Contact Info: http://cbio.mskcc.org/~lianos/contact