[Rd] Vignette questions

[Paul Gilbert]

On 12-04-12 03:15 AM, Uwe Ligges wrote:
>
>
> On 12.04.2012 01:16, Paul Gilbert wrote:
>>
>>
>> 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.
>
> No, this is all done automatically by R CMD build, hence you do not need
> to worry.

Now I am not sure if I am confused or if you missed the "if it cannot be 
built by R-forge and CRAN" part of my sentence. I understand that this 
is done automatically by R CMD build for vignettes that can be built on 
all, or most, R platforms. In the situation where R CMD build on R-forge 
will fail, or not result in a complete vignette pdf, I think it is 
necessary to put a good  pdf in inst/doc in order to get a build on 
R-forge that can be submitted to CRAN. That is, in situations like:

   -the vignette requires databases or drivers not generally available
   -the vignette (legitimately) takes forever to run
   -the vignette requires a cluster

I am now wondering what the recommended practice is. What I have been 
doing, which I thought was the recommended practice, is to put the 
vignette Rnw (Stex) file in vignettes/ and put a pdf, constructed on a 
machine that has appropriate resources, into inst/doc.  Is that the 
recommended way to proceed?

Related, some have commented that they put a pdf in inst/doc and then 
leave out the vignette Rnw file to avoid error messages. Is the 
discouraged or encouraged?

Paul
>
>
>>>
>>> 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,
>
> Well, yours are that specific that they rely on third party software.
> Vignettes "only" depending on R and installed packages that are declared
> as dependencies can be build by CRAN.
>
>
>> 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.)
>
> R CMD build will rebuild vignettes unless you ask R not to do so.
>
> Uwe
>
>
>>>
>>> 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