[Rd] Vignette questions

[Uwe Ligges]

On 12.04.2012 16:42, Paul Gilbert wrote:
>
>
> 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 cannot comment on R-forge - I just submit packages manually.


> 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?

Sounds OK for such a specific case (although I have not tested nor 
thought about it intensely before).

> 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?

Finding bugs in packages happens frequently by executing the code in the 
vignettes. So if the vignette builds and it does not take ages to build 
the vignette, I'd encourage people to submit vignette sources (also note 
the license that may make it unavoidable to ship the sources).

Uwe


>
> 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