processing of /vignettes and /inst/doc

An embedded and charset-unspecified text was scrubbed...
Name: not available
URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20130917/56fc2238/attachment.pl>
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
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
An embedded and charset-unspecified text was scrubbed...
Name: not available
URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20130917/db2ee8c4/attachment.pl>
Thanks a lot for the speedy fix.

It is a little unclear to me what "considers it to be a vignette" 
implies. Re-reading R-exts, it is pretty clear on
  vignettes, Sweave format
  vignettes, non-Sweave
but a little unclear on
  manuals, arbitrary format
except mentioning that they should go in /inst/doc.

Are such manuals not indexed by the help system?  Not found by 
vignettes() (and if so, is there another mechanism for discovering them)?
They would not be found by vignettes() or browseVignettes(), but would 
be listed on the HTML help page under "User guides, package vignettes 
and other documentation."

Duncan Murdoch