Yesterday, I submitted a package to CRAN that I had previously built using `R CMD build' (no extra arguments), and checked with 'R-devel CMD check --as-cran' (R-devel is my installation of the latest development version). No errors were reported in either of these steps.
However, the submitted package contained a LaTeX error in one of the vignettes -- it had \paragaph{} instead of \paragraph{}. And the submission bounced back from CRAN because their checking DID catch the error.
So I have two questions...
1. How could a LaTeX error in a vignette possibly get past either R CMD build or R CMD check --as-cran without errors being reported? (I'll mention that subsequently I manually ran Sweave and pdflatex on the vignette and it did report the error -- confirming that I don't have a \paragaph macro defined somewhere on my own system.) FWIW, this IS system-dependent, as I do get error messages if I try to build the package on a Mac Pro. But I don't use that as my primary machine, as it is old, slow, and a laptop. I have a Windows 7 Pro system, service pack 1,
MiKTeX-pdfTeX 2.9.5496 (1.40.15) (MiKTeX 2.9 64-bit). Perhaps there's something different about error flags returned by MiKTeX and how they interact with R.
2. I have struggled previously with vignettes, as they sometimes have not been re-built when I wanted them to be. So I have finally settled on just putting the source file and nothing else in the vignettes directory. But that's what messed me up, because I made a minor change and incorrectly trusted the build process with detecting any errors. Clearly, I don't fully understand how vignettes are handled. What's the best way to manage vignettes?
Thanks
Russ
Russell V. Lenth - Professor Emeritus
Department of Statistics and Actuarial Science
The University of Iowa - Iowa City, IA 52242 USA
Voice (319)335-0712 (Dept. office) - FAX (319)335-3017
[R-pkg-devel] Best practices for vignettes
7 messages · Dirk Eddelbuettel, Lenth, Russell V, Henrik Bengtsson
On 26 July 2015 at 18:42, Lenth, Russell V wrote:
| What's the best way to manage vignettes?
All the young ones will of course tell you to use Markdown :)
I still use Sweave / LaTeX as well, along with a custom driver: highlight, as
we once figured out how to make it create pretty shaded boxen with code (as
seen in the various Rcpp vignettes).
So for that I often keep a five-line script 'buildVignette.r' in the vignette
directory. With DESCRIPTION set up right (for the added vignette driver)
this then works in the package when it works manually for the tests.
And during the R CMD build ... ; R CMD INSTALL ... steps the vignette does
get rebuild.
Oh, but did I mention that markdown is easier? ;-) Earlier this year I
converted to writing my LateX Beamer presentation in RMarkdown (which
rmarkdown::render() then converts to LaTeX). I may, time permitting, look
into converting vignetts. But why mess with a working setup...
Dirk
PS buildVignette.r from an older package I am currently working on
#!/usr/bin/Rscript
## use given argument(s) as target files, or else default to .Rnw files in directory
files <- if (length(commandArgs(TRUE)) == 0) dir(pattern="*.Rnw") else commandArgs(TRUE)
## convert all files from Rnw to pdf using the highlight driver
invisible(sapply(files, function(srcfile) {
Sweave(srcfile, driver=highlight::HighlightWeaveLatex(boxes=TRUE))
tools::texi2pdf(gsub(".Rnw", ".tex", srcfile))
}))
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
On 26 July 2015 at 14:22, Dirk Eddelbuettel wrote:
|
| On 26 July 2015 at 18:42, Lenth, Russell V wrote:
| | What's the best way to manage vignettes?
|
| All the young ones will of course tell you to use Markdown :)
|
| I still use Sweave / LaTeX as well, along with a custom driver: highlight, as
| we once figured out how to make it create pretty shaded boxen with code (as
| seen in the various Rcpp vignettes).
|
| So for that I often keep a five-line script 'buildVignette.r' in the vignette
| directory. With DESCRIPTION set up right (for the added vignette driver)
| this then works in the package when it works manually for the tests.
I was rambling here. What I meant to say is
- buildVignette.r as shown below allows me to build the vignette on the spot
outside of package builds -- ie when I am in "vignette writing mode"
- if the vignette builds during the manual builds, which by their design
mock what the package build process does, then I am reasonably confident
that the R CMD ... process works too.
Hope this clarifies.
Dirk
|
| And during the R CMD build ... ; R CMD INSTALL ... steps the vignette does
| get rebuild.
|
| Oh, but did I mention that markdown is easier? ;-) Earlier this year I
| converted to writing my LateX Beamer presentation in RMarkdown (which
| rmarkdown::render() then converts to LaTeX). I may, time permitting, look
| into converting vignetts. But why mess with a working setup...
|
| Dirk
|
|
| PS buildVignette.r from an older package I am currently working on
|
| #!/usr/bin/Rscript
|
| ## use given argument(s) as target files, or else default to .Rnw files in directory
| files <- if (length(commandArgs(TRUE)) == 0) dir(pattern="*.Rnw") else commandArgs(TRUE)
|
| ## convert all files from Rnw to pdf using the highlight driver
| invisible(sapply(files, function(srcfile) {
| Sweave(srcfile, driver=highlight::HighlightWeaveLatex(boxes=TRUE))
| tools::texi2pdf(gsub(".Rnw", ".tex", srcfile))
| }))
|
|
| --
| http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
|
| ______________________________________________
| R-package-devel at r-project.org mailing list
| https://stat.ethz.ch/mailman/listinfo/r-package-devel
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
Thanks, Dirk. Well, I tried this (after suitable modification), and what it does is create all the intermediate files, graphics files, an .Rout file, etc. in the vignette directory. And even then, for some reason it didn't build the pdfs correctly. So I had a mess to clean up. I've tried Markdown a few times, and technically, I guess it works. But I always find myself abandoning it later because it gives me what it wants instead of what I want. I suppose I could learn more of its refinements, but even then it doesn't seem very promising. I'm not too old to learn new things, but at my age, I think I am empowered to choose what I want to learn -- and expertise on Markdown is just not a big priority. Russ -----Original Message----- From: Dirk Eddelbuettel [mailto:edd at debian.org] Sent: Sunday, July 26, 2015 2:31 PM To: Dirk Eddelbuettel <edd at debian.org> Cc: Lenth, Russell V <russell-lenth at uiowa.edu>; r-package-devel at r-project.org Subject: Re: [R-pkg-devel] Best practices for vignettes
On 26 July 2015 at 14:22, Dirk Eddelbuettel wrote:
|
| On 26 July 2015 at 18:42, Lenth, Russell V wrote:
| | What's the best way to manage vignettes? | | All the young ones will of course tell you to use Markdown :) | | I still use Sweave / LaTeX as well, along with a custom driver: | highlight, as we once figured out how to make it create pretty shaded | boxen with code (as seen in the various Rcpp vignettes). | | So for that I often keep a five-line script 'buildVignette.r' in the | vignette directory. With DESCRIPTION set up right (for the added | vignette driver) this then works in the package when it works manually for the tests. I was rambling here. What I meant to say is - buildVignette.r as shown below allows me to build the vignette on the spot outside of package builds -- ie when I am in "vignette writing mode" - if the vignette builds during the manual builds, which by their design mock what the package build process does, then I am reasonably confident that the R CMD ... process works too. Hope this clarifies. Dirk
Have a look at tools::buildVignette() - it builds a vignette the same way as R CMD build does it. It's a good start for troubleshooting. /Henrik On Mon, Jul 27, 2015 at 1:31 AM, Lenth, Russell V
<russell-lenth at uiowa.edu> wrote:
Thanks, Dirk. Well, I tried this (after suitable modification), and what it does is create all the intermediate files, graphics files, an .Rout file, etc. in the vignette directory. And even then, for some reason it didn't build the pdfs correctly. So I had a mess to clean up. I've tried Markdown a few times, and technically, I guess it works. But I always find myself abandoning it later because it gives me what it wants instead of what I want. I suppose I could learn more of its refinements, but even then it doesn't seem very promising. I'm not too old to learn new things, but at my age, I think I am empowered to choose what I want to learn -- and expertise on Markdown is just not a big priority. Russ -----Original Message----- From: Dirk Eddelbuettel [mailto:edd at debian.org] Sent: Sunday, July 26, 2015 2:31 PM To: Dirk Eddelbuettel <edd at debian.org> Cc: Lenth, Russell V <russell-lenth at uiowa.edu>; r-package-devel at r-project.org Subject: Re: [R-pkg-devel] Best practices for vignettes On 26 July 2015 at 14:22, Dirk Eddelbuettel wrote: | | On 26 July 2015 at 18:42, Lenth, Russell V wrote: | | What's the best way to manage vignettes? | | All the young ones will of course tell you to use Markdown :) | | I still use Sweave / LaTeX as well, along with a custom driver: | highlight, as we once figured out how to make it create pretty shaded | boxen with code (as seen in the various Rcpp vignettes). | | So for that I often keep a five-line script 'buildVignette.r' in the | vignette directory. With DESCRIPTION set up right (for the added | vignette driver) this then works in the package when it works manually for the tests. I was rambling here. What I meant to say is - buildVignette.r as shown below allows me to build the vignette on the spot outside of package builds -- ie when I am in "vignette writing mode" - if the vignette builds during the manual builds, which by their design mock what the package build process does, then I am reasonably confident that the R CMD ... process works too. Hope this clarifies. Dirk
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
On 27 July 2015 at 12:50, Henrik Bengtsson wrote:
| Have a look at tools::buildVignette() - it builds a vignette the same | way as R CMD build does it. It's a good start for troubleshooting. Seconded. | /Henrik | | On Mon, Jul 27, 2015 at 1:31 AM, Lenth, Russell V
| <russell-lenth at uiowa.edu> wrote:
| > Thanks, Dirk. Well, I tried this (after suitable modification), and what it does is create all the intermediate files, graphics files, an .Rout file, etc. in the vignette directory. And even then, for some reason it didn't build the pdfs correctly. So I had a mess to clean up. If you have the patience, you probably want to debug this piece by piece, and maybe making the vignette (temporarily) smaller and smaller and less dependent on other things. Sometimes it is the little things. I once had 'build/' in .Rbuildignore because I thought it was spurious. Not so. Tooks more than one iteration, countless feeble attempts and an eventual hint from a CRAN maintainer. Another debugging strategy is to grab a (small enough) existing package by someone else and see _exactly_ how it is setup. Lastly, "if you can't beat'em" ... I do have some Markdown vignettes in a newer package (drat) and that works well. Doesn't look as perfect as a pdf, but html rendering has its charms and uses. Dirk
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
Thanks. This helped me learn a few things... 1. buildVignettes() operates on an installed package. So in RStudio, I do "build and reload" and it copies the vignette sources to the right place. Unfortunately, it does not also copy the associated .bib file, and it erases the one already there. So I have to manually copy it each time. However, I could script this and thus be able to get a reliable test of the vignettes. 2. I now know why I didn't get a build error. For testing, I put my LaTeX error back in the vignette... -- On Windows with MikTeX, buildVignettes() reports only a warning that the pdflatex process returned an exit code of 1. -- On the Mac with TeX Live, I get an error, not just a warning. I suspect that TeX Live returns a higher error code for the same error. Most important, it appears that developers who use Windows with MikTeX should be advised that they will NOT detect certain LaTeX errors in routine building and checking. It might be worth switching to a different Windows installation of TeX. Russ -- Russell V. Lenth - Professor Emeritus Department of Statistics and Actuarial Science The University of Iowa - Iowa City, IA 52242 USA Dept office (319)335-0712 - FAX (319)335-3017 russell-lenth at uiowa.edu - http://www.stat.uiowa.edu/~rlenth/
From: Henrik Bengtsson [henrik.bengtsson at ucsf.edu]
Sent: Monday, July 27, 2015 5:50 AM
To: Lenth, Russell V
Cc: Dirk Eddelbuettel; r-package-devel at r-project.org
Subject: Re: [R-pkg-devel] Best practices for vignettes
Sent: Monday, July 27, 2015 5:50 AM
To: Lenth, Russell V
Cc: Dirk Eddelbuettel; r-package-devel at r-project.org
Subject: Re: [R-pkg-devel] Best practices for vignettes
Have a look at tools::buildVignette() - it builds a vignette the same way as R CMD build does it. It's a good start for troubleshooting. /Henrik