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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
