[Rd] Vignette questions

[Paul Gilbert]

On 12-04-11 04:41 PM, Terry Therneau wrote:
> Context: R2.15-0 on Ubuntu.
>
> 1. I get a WARNING from CMD check for "Package vignette(s) without
> corresponding PDF:
> In this case the vignettes directory had both the pdf and Rnw; do I need
> to move the pdf to inst/doc?

Yes, you need to put the pdf in the inst/doc directory if it cannot be 
built by R-forge and CRAN check machines, but leave the Rnw in the 
vignettes directory.
>
> I'm reluctant to add the pdf to the svn source on Rforge, per the usual
> rule that a code management system should not have both a primary source
> and a object dervived from it under version control. However, if this is
> the suggested norm I could do so.

Yes, I think this is the norm if the vignette cannot be built on CRAN 
and R-forge, even though it does seem a bit strange. However, you do not 
necessarily need to update the vignette pdf in inst/doc every time you 
make a change to the package even though, in my opinion, the correct 
logic is to test remaking the vignette when you make a change to the 
package. You should do this testing, of course, you just do not need to 
put the new pdf in inst/doc and commit it to svn each time. (But you 
should probably do that before you build the final package to put on CRAN.)

>
> 2. Close reading of the paragraph about vignette sources shows the
> following -- I think? If I have a vignette that should not be rebuilt by
> "check" or "BUILD" I should put the .Rnw source and pdf in /inst/doc,
> and have the others that should be rebuilt in /vignettes. This would
> include any that use "private R packages, screen snapshots, ...", or in
> my case one that takes just a little short of forever to run.

I don't think it is intended to say that, and I didn't read it that way. 
I think putting the Rnw in inst/doc is supported (temporarily?) for 
historical reasons only. If it is not in vignettes/ and is found in 
inst/doc/, it is treated the same way as if it were in vignettes/.

You can include screen snapshots, etc, in either case. For your 
situation, what you probably do need to do is specify  "BuildVignettes: 
false" in the DESCRIPTION file. This prevents the pdf for inst/doc from 
being generated by the the Rnw. However, it does not prevent R CMD check 
from checking that the R code extracted from the Rnw actually runs, and 
generating an error if it does not. To prevent testing of the R code, 
you have to appeal directly to the CRAN and R-forge maintainers, and 
they will put the package on a special list. You do need to give them a 
good reason why the code should not be tested. I think they are 
sympathetic with "takes forever to run" and not very sympathetic with 
"does not work anymore". Generally, I think they want to consider doing 
this only in exceptional cases, so they do not get in a situation of 
having lots of broken vignettes. (One should stick with journal articles 
for recording broken code.)

> 3. Do these unprocessed package also contribute to the index via
> \VignetteIndexEntry lines, or will I need to create a custom index?

I'm not sure of the answer to this, but would be curious to know. You 
may need to rely on voodoo.

Paul
>
> Terry Therneau
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel