[Rd] How to document man/*.Rd pages with images?

[Steve Lianoglou]

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