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

[Simon Urbanek]

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

> i got the original idea from
> 
> http://romainfrancois.blog.free.fr/index.php?post/2010/04/03/embed-images-in-Rd-documents
> 
> i really won't mind if this is removed. i can put a "clean" package online. Didn't mean to do any harm.
> 

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


> 
> 2011/5/11 Simon Urbanek <simon.urbanek at r-project.org>
> 
> On May 11, 2011, at 4:16 PM, Thomas Roth wrote:
> 
> > Well, it takes 5 seconds on a regular notebook... which i have
> >
> > Basically there's small simulation going on, so if you don't need any simulation just  a small plot it will go in less then a second. Haven't seen any other solution :-)
> >
> 
> 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
> 
> 
> > it only takes long because there's a simulation going on in the background...
> >
> > 2011/5/11 Simon Urbanek <simon.urbanek at r-project.org>
> >
> > On May 11, 2011, at 4:00 PM, Thomas Roth wrote:
> >
> >> Hi,
> >>
> >> There's a possibility to put images into documentation files. Have a look at
> >> the package visualizationTools to see how it works. The original idea is/was
> >> by Romain Francois as far as i remember.
> >>
> >> For instance have a look at the documentation for the function CLT
> >>
> >
> > Interesting - ?CLT takes forever (about 30s) on a fairly fast machine (8-core Xeon) - every time! That sort of defeats the purpose of help pages ... so whatever it's doing (behind your back - the help in the console still shows no images, obviously), I would not recommend it as it makes the help unusable.
> >
> > Cheers,
> > S
> >
> >
> >>
> >> 2011/5/11 Hadley Wickham <hadley at rice.edu>
> >>
> >>>> 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
> >>>
> >>> 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
> >>>
> >>> --
> >>> Assistant Professor / Dobelman Family Junior Chair
> >>> Department of Statistics / Rice University
> >>> http://had.co.nz/
> >>>
> >>> ______________________________________________
> >>> R-devel at r-project.org mailing list
> >>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>
> >>
> >>
> >> [[alternative HTML version deleted]]
> >>
> >>
> >> ______________________________________________
> >> R-devel at r-project.org mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> >
> 
>