Vignette questions

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