[Rd] Vignette questions
pgilbert902 at gmail.com
Thu Apr 12 01:16:42 CEST 2012
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
> 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.
> Terry Therneau
> R-devel at r-project.org mailing list
More information about the R-devel