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

The long run intention is that vignettes will be in the vignettes 
directory, and nowhere else.  Files in inst/doc will be installed, but 
they are not vignettes, they are just documentation files.  This has 
been documented for a long time, but it hasn't been enforced.

The new change is that vignettes will be produced at build time, by the 
package maintainer, not by the user, at INSTALL time.  Version 3.0.2 is 
intended to handle tar.gz files built under earlier versions of R 
according to the old rules, and also tarballs built under the new system.

So how your example below is handled depends on which version built the 
tarball.  I'll assume everything is being done with 3.0.2 beta.
>
> 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

Since this package has a vignettes directory, it's assumed that that is 
where the vignettes are.  So the current version doesn't see 
inst/doc/big.Rnw as a vignette.

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

That looks like a bug, in that inst/doc/big.pdf should still have been 
included as a non-vignette documentation file.  I'll look into that.
>
> 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."

That statement should be correct, hence current behaviour is a bug.

Duncan Murdoch

>
> 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.
>
> Best,
> Kasper
>
> 	[[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel