[Rd] Requests for vignette clarification (re: Writing R Extensions)

From: Paul Johnson <pauljohn32_at_gmail.com>
Date: Fri, 01 Jun 2012 13:53:41 -0500

I apologize that these questions are stupid and literal.

I write to ask for clarification of comments in the R extensions manual about vignettes. I'm not great at LaTeX, but I'm not a complete novice either, and some of the comments are puzzling to me.

  1. I'm stumbling over this line:

"Make sure all files needed to run the R code in the vignette (data
sets, ...) are accessible by either placing them in the inst/doc hierarchy of the source package or by using calls to system.file()."

Where it says "inst/doc", can I interpret it to mean "vignettes"? The vignette files are under vignettes. Why wouldn't those other files be in there? Or does that mean I'm supposed to copy the style and bib files from the vignettes folder to the inst/doc folder? Or none of the above :)

2. I'm also curious about the implications of the parenthesized section of this comment:

"By default R CMD build will run Sweave on all files in Sweave format
in vignettes, or if that does not exist, inst/doc (but not in sub-directories)."

At first I though that meant it will search vignettes and subdirectories under vignettes, or it will look under inst/doc, but no subdirectories under inst/doc. So I created vignettes in subdirectories under vignettes and they are ignored by the build process, so that was obviously wrong. For clarification, it would help me if the manual said

"By default R CMD build will run Sweave on all files in Sweave format
in vignettes (but not in sub-directories), or if that does not exist, inst/doc ."

In this list I've read several questions/complaints from people who don't want their vignettes rebuild during the package check or build process, and I wondered if there is a benefit to having vignettes in subdirectories. Could inclusion of troublesome vignettes in subdirectories be a way that people can circumvent the rebuilding and re-checking of vignettes during build, check, or install? If I build my vignettes manually and copy the pdf output over to inst/doc, will those pdf files be "legitimate" vignette files as far as CRAN is concerned? The writeup in R Extensions is a little bit confusing on that point.

"By including the PDF version in the package sources it is not
necessary that the vignette PDFs can be re-built at install time, i.e., the package author can use private R packages, screen snapshots
and LaTeX extensions which are only available on his machine."

Its just confusing, that's all I can say about it.

I could learn how to do this from some examples of packages that manage vignettes the "right way", if you could tell me which ones are
"right" :) I'd like to see one that has a Makefile, uses a bib file,
and, if possible, one that imports a pdf file from elsewhere. If there is one that uses subdirectories under vignettes to keep separate  the content of vignettes, that would be extra helpful.

I'm eager to do this in the correct way, just point me at some that are proper.


Paul E. Johnson
Professor, Political Science    Assoc. Director
1541 Lilac Lane, Room 504     Center for Research Methods
University of Kansas               University of Kansas
http://pj.freefaculty.org            http://quant.ku.edu

R-devel_at_r-project.org mailing list
Received on Fri 01 Jun 2012 - 18:57:59 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Mon 04 Jun 2012 - 13:42:19 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive