Skip to content

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

25 messages · Sean Robert McGuffee, Dan Tenenbaum, Steve Lianoglou +6 more

Original
Sean Robert McGuffee
# 
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
Dan Tenenbaum
# 
On Wed, May 11, 2011 at 12:08 PM, Sean Robert McGuffee
<sean.mcguffee at gmail.com> wrote:
Given a graphics file called foo.png, you can include it in a vignette
as follows:
\includegraphics[width=0.5\textwidth]{foo}

http://amath.colorado.edu/documentation/LaTeX/reference/figures.html
Dan
Hadley Wickham
# 
I think you're asking the wrong question.  You should be asking: "Can
I include images in help files?".  As far as I know, the answer is no.

You might be able to do it for specific output formats.  See
http://cran.r-project.org/doc/manuals/R-exts.html#Conditional-text

Hadley
Steve Lianoglou
# 
Hi,

On Wed, May 11, 2011 at 3:42 PM, Sean Robert McGuffee
<sean.mcguffee at gmail.com> wrote:
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 actually don't believe you can do this.
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".
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
Paul Gilbert
# 
I thought the usual logic was that you might put graphs and images into a vignette, and you might refer to the vignette in an Rd help file, but you would not put the graphs into the help because ? access to the page cannot assume that you actual have a graphics device. Of course, examples in the Rd file can generate the graphs.

Paul
====================================================================================

La version fran?aise suit le texte anglais.

------------------------------------------------------------------------------------

This email may contain privileged and/or confidential in...{{dropped:26}}
Simon Urbanek
#
On May 11, 2011, at 4:16 PM, Thomas Roth wrote:

            

      
      
      
    

        
Oh, my ... it's worse than I thought. Not only does it run things so you have to wait forever - it actually installs packages behind your back!  Wow, now there is the nightmare abuse of \Sexpr - the malicious package retrieves private data from your machine and deletes your files... and I was worrying about leaving a tiny crack open for Rhttpd injection attacks - yet there is a big gaping door open to all packages ... Does it mean we need more stringent checks on Rd files now as well since they contain code?

What is interesting, though, is that the code gets executed even if html is not the back-end (e.g., in terminal) .. is this a bug? 

Cheers,
S

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        
      

    

    

      
      

        


  

        

      Sean Robert McGuffee
    

    

      
      #
    

  


  

      
On 5/11/11 4:20 PM, "Paul Gilbert" <pgilbert at bank-banque-canada.ca> wrote:

        

            

      
      
      
    

        
My understanding was that one can require graphics for a package that does
require graphics, right?

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Sean Robert McGuffee
    

    

      
      #
    

  


  

      
On 5/11/11 4:20 PM, "Paul Gilbert" <pgilbert at bank-banque-canada.ca> wrote:

        

            

      
      
      
    

        
My understanding was that one can require graphics for a package that does
require graphics, right?

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Simon Urbanek
    

    

      
      #
    

  


  

      
On May 11, 2011, at 4:43 PM, Thomas Roth wrote:

        

            

      
      
      
    

        
Well, except it does things that the user did not ask for (such as installing packages). Yes, it is "clean" in that the intention was benign, but modifying local file system other than the temporary directory is a transgression - especially since the user doesn't know about it. But it does raise a serious question about "invisible" code -- most R code is visible as the user can look at functions or read examples, but the \Sexpr code is invisible (you have to go to the sources to find out what it does -- admittedly, the same is true for the C/FORTRAN code) and I'm not sure whether it's checked.

Just to reiterate - the other point was that whatever you do, should not hamper the usability and performing a taking 30s to display a help page is doing so. (FWIW it's not the simulation that takes up the time - it's the plotting and since you fixed the seed there is really no point to re-render it -- you can as well do as Paul suggested, just ship the rendered image with the package..)

Cheers,
Simon

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
On 11/05/2011 4:35 PM, Simon Urbanek wrote:

            

      
      
      
    

        
I don't think it's any more of a security problem than packages have 
always had, since they can execute arbitrary code when you load them.

            

      
      
      
    

        
The docs say that \Sexpr is evaluated before \if, so probably not...

Duncan Murdoch

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
On 11/05/2011 4:45 PM, Sean Robert McGuffee wrote:

            

      
      
      
    

        
No, there's no simple way to require particular hardware, or particular 
user options (e.g. options(help_type="text") would mean no HTML).  The 
startup code for a package might be able to check for the hardware and 
abort if it is unavailable, but a user could change help type at any time.

Duncan Murdoch

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        
      

    

    

      
      

        


  

        

      Hadley Wickham
    

    

      
      #
    

  


  

          

      
      
      
    

        
As long as you realise Rd files can run arbitrary R code, you're no
worse off than you were before Rd files could run code.  No one is
checking that there's not a function in ggplot2 that secretly sends me
all your code and data ;)

Hadley

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Paul Gilbert
    

    

      
      #
    

  


  

          

      
      
      
    

        
Well, it is open source so we could check it.  Hopefully you are checking this yourself, because it would be a criminal offense to do that. ;)

Paul
====================================================================================

La version fran?aise suit le texte anglais.

------------------------------------------------------------------------------------

This email may contain privileged and/or confidential information, and the Bank of
Canada does not waive any related rights. Any distribution, use, or copying of this
email or the information it contains by other than the intended recipient is
unauthorized. If you received this email in error please delete it immediately from
your system and notify the sender promptly by email that you have done so. 

------------------------------------------------------------------------------------

Le pr?sent courriel peut contenir de l'information privil?gi?e ou confidentielle.
La Banque du Canada ne renonce pas aux droits qui s'y rapportent. Toute diffusion,
utilisation ou copie de ce courriel ou des renseignements qu'il contient par une
personne autre que le ou les destinataires d?sign?s est interdite. Si vous recevez
ce courriel par erreur, veuillez le supprimer imm?diatement et envoyer sans d?lai ?
l'exp?diteur un message ?lectronique pour l'aviser que vous avez ?limin? de votre
ordinateur toute copie du courriel re?u.

  
  


  


      

    

    

      
      

        
      

    

    

      
      

        


  

        

      Simon Urbanek
    

    

      
      #
    

  


  

      
I just want to clarify the mechanics of the help system when using html.

R has a built-in HTTP server (aka Rhttpd) which transforms HTTP requests to function calls. It is not your usual web server, because it doesn't map URL paths to files, it just allows R functions to do anything with it -- something like CGI except that we are talking about functions and not files. Therefore you won't find any files and there is no file structure involved.

For the help system, the function handling the requests is tools:::httpd() - you can look at what it does. Basically, it generates pages according to the various paths it supports. As part of its path handling it allows certain paths to reference files, e.g. /library/myPackage/doc/randomStuffInPackagesDocDirectory.html will read the file doc/randomStuffInPackagesDocDirectory.html in myPackage.

Note that the whole point of the dynamic help *is* to generate content on the fly, because the content depends on the state of your current workspace -- packages loaded, classes defined, etc. so you cannot pre-generate pages as they won't have correct links - that's why we shifted from static html pages to the dynamic ones.


I'm curious about "If it?s a large picture this process nearly crashes my machine when trying to access the file via help" - do you have an example package that would illustrate the problem?

Thanks,
Simon

        
On May 11, 2011, at 7:14 PM, Sean Robert McGuffee wrote:

        

            

      
      
      
    

  
  


  


      

    

    
1 day later

    

      
      

        


  

        

      Sean Robert McGuffee
    

    

      
      #
    

  


  

      
On 5/12/11 9:13 AM, "Simon Urbanek" <simon.urbanek at r-project.org> wrote:

        

            

      
      
      
    

        
Awesome, will do!

            

      
      
      
    

        
This is interesting. It actually speaks to a constructive criticism I have
of R. As a user of R, I don't want to have conditional dynamic help. I want
to always get the same answer to a question so to say. If there is a way to
do something that works and is reproducible, then I don't want to maybe or
maybe not get that answer. Thus, I guess what I'm thinking is that there
should maybe be selection within help that has organization based on
packages loaded and classes defined, but I would hope that the state of my
system doesn't change the help that is displayed. At least I as one user
would prefer to see all of my options will all packages and not have any of
it emphasized or excluded by how my system is currently set up.

In the satus quo, I can see how the choice of which pages to look at is
dynamic if more than one comes up on a search, but it seems inefficient to
me to have the page itself be dynamic. I think it would be a good idea if
package authors could at least have an option to have their help pages
produced as files either way. I mean, when my package will be loaded, I
certainly won't want options and do want to be able to point my users to an
unconditional file location to point their browser to.

            

      
      
      
    

        
I?ve tried to recreate the problem with a small fake package, and although
it passes the check it doesn?t seem to work quite right on my system. I
might have some compiler issues or configuration issues though, so it might
work as is on your system. If not, I think you could quickly find the
relevant parts though and add them to a package of your own to see the bug
if this doesn?t work as is on your machine. I?m not really sure why this
doesn?t work on my machine. I did almost exactly the same thing as in the
huge package that I can?t fit on my file transfer site. However, it is set
up to only install in 64-bit and I couldn't remember how I set that up. So
it might be the 32-bit part that is messing things up on my system. I think
there should be a simple way to declare an architecture in a package
DESCRIPTION or something. I can't remember. Anyway, that's beside the point.
Here is an example of a syntax and image file that makes my help go
extremely slow and not show images:

http://ftsext.mskcc.org/FileExchange/FileList.aspx?id=9afb4fe1-ce1c-406d-b1a
1-c9360493137c

Please let me know if you see why this isn?t working for me--both as to if
this works as is on your system and as to if this causes the bug. At the
moment this tells me " Error in gzfile(file, "rb") : cannot open the
connection" even though it passes all the build check install tests on my
machine.

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Simon Urbanek
    

    

      
      #
    

  


  

      
On May 13, 2011, at 7:08 PM, Sean Robert McGuffee wrote:

        

            

      
      
      
    

        
I don't think I follow you. Your options will be different, by definition, depending on which packages you have installed and loaded. As one obvious example, you can't refer to documentation of packages that you did not install. As another example (more future-directed I suspect), the generics and methods depend on your currently defined classes, methods etc. That is true in R itself, so I don't see why you would prefer documentation that doesn't match your R.

            

      
      
      
    

        
That decision is left to the user - you can use --html to generate html pages.

            

      
      
      
    

        
You can do that with dynamically generated pages (you can't do that with static pages in fact) - the paths are well defined (unlike in your file system). Even better is fact, because the dynamic help is smart enough to find packages in different libraries, for example.

            

      
      
      
    

        
There seem to be two bugs AFAICS:

a) The path generated from the URL is either wrong or something is not in syncs - it says
/Library/Frameworks/R.framework/Versions/2.13/Resources/library/Meta/Rd.rdsBug/help
but the meta file is really in
/Library/Frameworks/R.framework/Versions/2.13/Resources/library/helpBug/Meta/Rd.rds
It seems like some strange permutation issue - but I didn't look at httpd() yet (I'm a bit puzzled as of why it doesn't affect other packages - maybe it's some regexp thing ...).

b) there seems to be an issue with WebKit and Rhttpd interaction in that Rhttpd gets blocked by WebKit not fetching the data. If you look at the page from an external browser, all is well. This will be a bit tricky to address and will need modifications to R...

Cheers,
Simon

            

      
      
      
    

  
  


  


      

    

    
2 days later

    

      
      

        


  

        

      Sean Robert McGuffee
    

    

      
      #
    

  


  

      
On 5/13/11 8:20 PM, "Simon Urbanek" <simon.urbanek at r-project.org> wrote:

        

            

      
      
      
    

        
I guess what I mean to say is that although a user's options depend on
context, when I use help, I want to know what my options are outside of the
current context. Especially at a stage where I need help, I definitely might
not have the right context set up, so it's very important to me to have
non-context-specific help. I recognize that this is my opinion and by no
means agreed upon, but this was a huge barrier for me when I first began
using R. For example, sometimes I would load a library while following an
example in the documentation before I even knew about libraries or realized
what I was doing. Then, within that context, a help command within that
library would work. On another day, when I hadn't set up that context by
accident, using my notes of "help(whatever)" wouldn't work. That was very
confusing and frustrating for me, and I'm much more computer literate than
many of the test-tube wet lab scientists I would hope to have using my
packages. I realize that "??whatever" gets around this, but the "??" symbol
is hard to lookup and learn about, especially when there is a
"help(whatever)" syntax that worked on a previous day. It took me months to
understand that "??" even existed as something separate from
"help(whatever)." In general, as a beginner, I found it very confusing that
there were more than one help commands, and I'm not sure if that's a good
thing for people who need help. Those are my two cents anyway. This might be
best for most people--I tend to be a very literal and concrete thinker and
may not be very representative. On the other hand, I don't see what the
benefit is to having less options for help if a package isn't loaded. I
suppose it provides more focus for someone who knows very well what they are
doing and wants to know something specific to their current context.
However, I'm not sure if helping that person focus is as critical to
providing help as assisting a new user who is likely to be oblivious to
contexts as a concept. Am I making any sense?

Let me make up an extreme example, just to clarify:
Suppose there are packages A and B, both with command C.
Regardless of what packages I have loaded, I would want help( C ) to bring
up a list with two files to choose from: one corresponding to A::C and one
corresponding to B::C, both containing the information that to use C one
must first type library(A) or library(B) to create the context that makes
the help information about how to use C relevant. My understanding is that
as it stands, typing help( C ) would do one of three things, depending on
whether library(A) or library(B) has been loaded. If neither has been
loaded, help( C ) would produce an error. If library(A) had been loaded,
then help would be generated regarding A::C and the user would be otherwise
oblivious to B::C, even if that were the useful info to the user. Likewise
for the vis-a-versa case with library(B) loaded. So that's to help me
explain my perspective of what I mean by non-context-specific help and why I
think it would be advantageous. Does that make sense? What I don't
understand is a case where it is advantageous to be oblivious to out of
context options. Could someone show me an example of that? I'm sure I am
missing something because I can't think of a case like that on my own and
have been considering it for days.

            

      
      
      
    

        
This is appealing to me, but I can't seem to find any info about it. Maybe
having the "--" part of the "--help" is throwing off my searches. I couldn't
find "--help" when I searched R's help. If my package is named MyPackage,
how would a user generate the html pages from it with "--html"?

            

      
      
      
    

        
I think this is a very good thing. Having the dynamic help is probably the
very best way to go from that perspective. I personally find file-system
paths to be annoyingly less well defined, so I'm completely sold by what you
are saying. It seems from what you said below that the performance issue I
have is from a bug. Am I right about that? I could be mistaking the context
of what you said below because I was a bit ambiguous about more than one
issue below. Since I can control what my package generates for help my
context-specific issue is not a problem for me, so a this is a distinct
issue I have with dynamic help and what appeared to me to be a performance
problem. My machine tends to lag for quite a while on many packages when
using the dynamic help system. Almost enough to discourage use. I found my
case with a large image to be a particularly bad anecdotal example of a
specific help problem, and maybe it is relevant to that more general issue
if there is a general bug. If this is caused by a bug, I would see no
problem with the concept of dynamic help at all--especially if it can react
instantaneously. However, I'm not completely convinced of that yet. It seem
very efficient to me to have a dynamic system point to pre-generated files.
However, generating those files dynamically, especially if many of them are
relevant, seems potentially inefficient. I don't claim to understand how it
is working yet, although looking into it has been fascinating so far.

            

      
      
      
    

        
Should I look into making these modifications to R? Or would this type of
thing be addressed by more official R personnel?

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Hervé Pagès
    

    

      
      #
    

  


  

      
Hi Sean,

        
On 11-05-16 11:15 AM, Sean Robert McGuffee wrote:

            

      
      
      
    

        
[...]

            

      
      
      
    

        
I guess by "user" Simon meant the person who installed the package
(--html is an option to R CMD INSTALL), which AFAICT is not necessarily
the same as the user. In any case, it seems that this is not in the
hands of the package author.

H.