Re: [Rd] Vignette questions

From: Paul Gilbert <pgilbert902_at_gmail.com>
Date: Wed, 11 Apr 2012 19:16:42 -0400

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



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Wed 11 Apr 2012 - 23:19:16 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Thu 12 Apr 2012 - 07:30:43 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive