[Rd] processing of /vignettes and /inst/doc

[Duncan Murdoch]

On 17/09/2013 9:56 AM, Kasper Daniel Hansen wrote:
> It is stated in R-exts that Sweave files (.Rnw) are either processed in
> /vignettes or /inst/doc, not both.  Furthermore, it is stated that external
> manuals and other files in /inst/doc will be installed.
>
> This behaviour has been used to deal with the situation where a package has
> two "vignettes", one that is easily processed and one that has a long
> running time.  This could be done by having
>    /vignettes/small.Rnw
>    /inst/doc/big.pdf
> with obvious notation.  Now, big.pdf is really produced by a Sweave
> document, so what we really have is
>    /vignettes/small.Rnw
>    /inst/doc/big.pdf
>    /inst/doc/big.Rnw
>
> This used to work, in the sense that the tarball produced by R CMD build
> produced
>    /inst/doc/small.Rnw
>    /inst/doc/small.pdf
>    /inst/doc/big.pdf
>    /inst/doc/big.Rnw
>
> Recently (R-3.0.2 beta, specifically "R version 3.0.2 beta (2013-09-16
> r63937)"), the final tarball only has
>    /inst/doc/small.Rnw
>    /inst/doc/small.pdf
>    /inst/doc/big.Rnw
>
> If we remove
>    /inst/doc/big.Rnw
> the pdf gets included.  So it seems that the presence of
>    /inst/doc/big.Rnw
> prevents the pdf from being included.
>
> This seems to me to be unwanted behaviour, since R-exts says
>
> "In addition to the help files in Rd format, R packages allow the inclusion
> of documents in arbitrary other formats. The standard location for these is
> subdirectory inst/doc of a source package, the contents will be copied to
> subdirectory docwhen the package is installed."
>
> However, it is also clear that Sweave docs are "special".  Still, I believe
> the past behaviour was better and more in line with what I infer as the
> intended behaviour.
>
> An example is the ADaCGH2 package in Bioconductor which I am not involved
> with.  I include a cc to the maintainer who reported this on bioc-devel.

This was a bug in the cleanup code after vignettes were built:  it was a 
little too zealous, and cleaned up things it hadn't produced.
After fixing the bug, for a test case like the one described above, R 
3.0.2 will not build the big vignette, but will consider it to be a 
vignette.  R-devel will not consider it to be a vignette.  Both should 
install it into inst/doc in the tarball.

Duncan Murdoch