Skip to content

Vignette questions

12 messages · Terry Therneau, Yihui Xie, Claudia Beleites +3 more

Original
Terry Therneau
# 
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?

    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.

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.

3. Do these unprocessed package also contribute to the index via 
\VignetteIndexEntry lines, or will I need to create a custom index?

Terry Therneau
Yihui Xie
# 
For 1, you should run R CMD check on the tar ball (pkg_x.x.tar.gz)
from R CMD build instead of the source directory. R CMD build will
build the PDF vignette into the tar ball.

For 2, I have been confused by ./vignettes vs ./inst/doc since
./vignettes was introduced. I might be able to figure it out by
try-and-err but I never tried, and I'm still sticking to ./inst/doc.
At least you can exclude the Rnw source in .Rbuildignore so that R can
only stare at your PDF documents and sigh.

For 3, I remember some of us requested that R could also respect
entries of non-Sweave vignettes (like the ones in ./demo/00Index), but
this is not possible as far as I know. However, I can tell you a dark
voodoo seems to be still working: you can write your own index.html
under ./inst/doc with your own links to vignettes.

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 515-294-2465 Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA
On Wed, Apr 11, 2012 at 3:41 PM, Terry Therneau <therneau at mayo.edu> wrote:
Claudia Beleites
# 
Very quick & short answer:

I made the transition to  ./vignettes for hyperSpec (you can look at the source at r-forge) - it was a mess. It is almost working now (compression is missing, I'll have to figure out how to invoke ghostscript in an OS idependent way, qpdf doesn't give me the compression rates). 

I have .pdf is under version control only for those vignettes that I build externally (with the fake .Rnws that produce the proper indexing as vignette).  They are all (regardless whether BUILD and check affect them or not) in ./vignettes.
I think that strategy can at least partially solve the issue with non-Sweave vignettes as well as long as the result is a pdf.  
You may need to play with ./vignettes/.install_extras if additional, non pdf and non Rnw files are needed.


Best,

Claudia
Paul Gilbert
#
On 12-04-11 04:41 PM, Terry Therneau wrote:
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.
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.)
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.)
I'm not sure of the answer to this, but would be curious to know. You 
may need to rely on voodoo.

Paul
Uwe Ligges
#
On 12.04.2012 01:16, Paul Gilbert wrote:
No, this is all done automatically by R CMD build, hence you do not need 
to worry.
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.
R CMD build will rebuild vignettes unless you ask R not to do so.

Uwe
Uwe Ligges
#
On 11.04.2012 23:28, Yihui Xie wrote:
Just move vignette sources to :/vignettes in your package?

Uwe
Uwe Ligges
#
On 12.04.2012 00:23, beleites,claudia wrote:
R CMD build --compact-vignettes=gs

Uwe
Terry Therneau
#
On 04/12/2012 02:15 AM, Uwe Ligges wrote:
Suddenly it becomes clear:  the warning will disappear on its own when I 
apply CMD check to the tarball.

I was running it on the directory, as is my habit when I've just added a 
new feature and want to make sure I didn't break anything old, and had 
wandered down the "CRAN doesn't like warnings so I better fix this 
somehow" path.

Terry Therneau
Paul Gilbert
#
On 12-04-12 03:15 AM, Uwe Ligges wrote:
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
Uwe Ligges
#
On 12.04.2012 16:42, Paul Gilbert wrote:
I cannot comment on R-forge - I just submit packages manually.
Sounds OK for such a specific case (although I have not tested nor 
thought about it intensely before).
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
Yihui Xie
# 
If R-forge gives the warning, it is likely to be their configuration
problem (they may be running R CMD check on the original source
directory instead of the tarball), so it is better to report to
R-forge admins directly.

I believe Terry is correct and it is a better practice *not* to put
PDF vignettes under version control when they can be automatically
generated.

If vignettes are too complicated, I would suggest not to use vignettes
in a package at all. You can put a fake vignette in the package and
point to the real vignette elsewhere. You may see my knitr package for
example: http://cran.r-project.org/package=knitr I have a dozen of
real "vignettes" but they are not under ./inst/doc/ but under
./inst/examples/. They will not take CRAN any time to check or build,
but I can use them to check if my package works fine on them locally.
After I release a new version to CRAN, I build PDF vignettes and
upload to Github (https://github.com/yihui/knitr/downloads) so users
who do not want to build by themselves can download them directly.

So l'd like to propose to free CRAN from the burdensome tasks of
checkings if you can do it by yourself:
http://yihui.name/knitr/demo/vignette/

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 515-294-2465 Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA
On Thu, Apr 12, 2012 at 9:42 AM, Paul Gilbert <pgilbert902 at gmail.com> wrote:
Henrik Bengtsson
# 
To have a prebuilt/static PDF appear as package vignette in the help,
browseVignettes(), and on CRAN, you can do:

1. Copy the PDF to inst/doc/, e.g. inst/doc/manual.pdf
2. Create a dummy inst/doc/manual.Rnw that contains four lines or LaTeX code:

%\VignetteIndexEntry{User manual}
\documentclass{article}
\begin{document}
\end{document}
http://cran.r-project.org/web/packages/R.rsp/vignettes/NonSweaveVignettes.pdf

/Henrik
On Thu, Apr 12, 2012 at 1:07 PM, Yihui Xie <xie at yihui.name> wrote: