The knitr package has relatively recently added new notangle vignette engines, such as knitr::rmarkdown_notangle, that allow disabling of evaluation of vignette chunks. The general process of using knitr for vignettes is described here, while the specific notangle functionality is described in an answer to this question.
My problem is that I can't get this to work. I can get it to pass R CMD build by including the .html output in the vignettes directory (I also put a copy in inst/doc), but I can't get it to pass R CMD check unless I specify --no-build-vignettes, or unless I change the rmarkdown_notangle engine back to rmarkdown.
I have built a trivial package that contains the following vignette (in vignettes/notangle.rmd): it's available here.
<!--
%\VignetteEngine{knitr::rmarkdown_notangle}
%\VignetteIndexEntry{Supplementary Materials}
-->
A silly little vignette.
```{r}
2+2
```
My DESCRIPTION file includes
Suggests:
knitr,
VignetteBuilder: knitr
BuildVignettes: yes
When I try to run R CMD check I get
* checking re-building of vignette outputs ... NOTE
Error in re-building vignettes:
...
Error: processing vignette 'notangle.rmd' failed with diagnostics:
Failed to locate the ‘weave’ output file (by engine ‘knitr::rmarkdown_notangle’)
for vignette with name ‘notangle’. The following files exist in directory ‘.’:
‘notangle.rmd’
Using r-devel (2014-09-17 r66626), but also happens with 3.1.1.
The workaround (which I would strongly prefer to avoid) is to switch from R code chunks to generic code chunks (opens with triple-backtick, rather than triple-backtick+"r"), which Rmarkdown doesn't process.
I'm sure I'm doing something boneheaded. Any clues?
update: I can get what I need (stop all chunks from being evaluated) by explicitly adding eval=FALSE to the options of every chunk, but I'd still like to know what's going on ...
It is a bug in the current version of knitr, and it has been fixed in the development version 1.7.9, which will (hopefully) be v1.8 on CRAN in the future.
Related
I recently released a vignette with version 1.1 of my R package. The Rmd for the vignette can be found here. When I create the vignette locally, I see author information and the table of contents at the top of the vignette, as expected. However, when I submitted this package to CRAN and the vignette was created there, I no longer see the table of contents or author information. Does anyone know why this may be happening?
Thanks.
I glanced at your DESCRIPTION here and noticed that the VignetteBuilder field does not contain rmarkdown. Since you are using knitr::rmarkdown as an engine, I suspect that you need:
VignetteBuilder: knitr, rmarkdown
Here is a relevant paragraph from the R-exts manual:
The VignetteBuilder field names (in a comma-separated list) packages that provide an engine for building vignettes. These may include the current package, or ones listed in Depends, Suggests or Imports. The utils package is always implicitly appended. See Non-Sweave vignettes for details. Note that if, for example, a vignette has engine knitr::rmarkdown, then knitr provides the engine but both knitr and rmarkdown are needed for using it, so both these packages need to be in the VignetteBuilder field and at least suggested (as rmarkdown is only suggested by knitr, and hence not available automatically along with it). Many packages using knitr also need the package formatR which it suggests and so the user package needs to do so too and include this in VignetteBuilder.
This is not a guaranteed fix, but it is maybe a first step.
I am new to the R/exams package and I try to produce a pdf document from one of the templates provided by the developers. (http://www.R-exams.org/templates/confint3/)
I am able to compile a Rnw file into a HTML document using the commands
library("exams")
exams2html("confint3.Rnw")
When calling the function
exams2pdf("confint3.Rnw")
it gives the error message
! LaTeX Error: File `Sweave.sty' not found.
I have Latex installed and there are no problems using it in general. I do not understand:
Do I need to tell exams2pdf() the location of the latex installation?
Do I need to define a template (as plain.tex) first? How should it look like?
What is it that I do not understand?
I looked at the documentation of the exams package, I also tried exams2pdf() after installing and calling library("tinytex").
Any help where to look at or what to do is highly appreciated. Thank you!
Minimal example:
install.packages("exams")
install.packages("tth")
library("exams")
set.seed(1090)
exams2html("confint3.Rnw")
set.seed(1090)
exams2pdf("confint3.Rnw")
It is hard to diagnose what exactly goes wrong with the information provided. In any case, when running pdfLaTeX either through utils::texi2dvi() (the default when the R package tinytex is not installed) or through tinytex::latexmk() (the default when the R package tinytex is installed) does not find the Sweave.sty file provided by the R base system. What is not clear to me which LaTeX engine is running in the background: MikTeX on Windows?
There are several strategies that could resolve this issue:
Tell your LaTeX installation about the texmf directory provided by the R base system so that it is found no matter where on your system you call pdfLaTeX.
Use a different LaTeX installation, e.g., by installing TinyTeX (the LaTeX distribution) through tinytex (the R package): tinytex::install_tinytex(). This might be particularly attractive if you are not actually a LaTeX user and just need it to compile PDF exams.
Avoid using the Sweave.sty file in a custom template file, say myplain.tex. A suggestion for such a file is included at the end of this post.
Further details are discussed in this thread: https://tex.stackexchange.com/questions/153193/latex-error-sweave-sty-not-found
As for your three questions:
As already explained above: exams2pdf() leverages either utils::texi2dvi() or tinytex::latexmk(). So these need to know about the LaTeX installation - but this seems to be the case. They just don't find the texmf provided by base R.
You should not have to do this but it is certainly an option that you can use. As a starting point, run exams_skeleton(markup = "latex", writer = "exams2pdf"). Among other things this creates a templates folder where you could put the myplain.tex template below.
As I said above, it's hard to answer that with the information provided. Hopefully, one of the clues provided here gets you a couple of steps forward.
Content of myplain.tex:
\documentclass[a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{a4wide,graphicx,color,verbatim,url,fancyvrb,ae,amsmath,amssymb,booktabs,longtable,eurosym}
\newenvironment{question}{\item \textbf{Problem}\newline}{}
\newenvironment{solution}{\textbf{Solution}\newline}{}
\newenvironment{answerlist}{\renewcommand{\labelenumi}{(\alph{enumi})}\begin{enumerate}}{\end{enumerate}}
\providecommand{\tightlist}{\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setkeys{Gin}{keepaspectratio}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{fontshape=sl}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{}
\DefineVerbatimEnvironment{Scode}{Verbatim}{fontshape=sl}
\newenvironment{Schunk}{}{}
\begin{document}
\begin{enumerate}
%% \exinput{exercises}
\end{enumerate}
\end{document}
I'm developing an R package, and I'm trying to make a link from the manual of the package to its vignette (a pdf). I've make this in the R function code, and it works:
\link[=../doc/package.pdf]{package's User Manual}
The problem is that the devtools::check() complains with a warning, which also causes a delay in the process of revision when uploading to CRAN...
* checking Rd cross-references ... WARNING
Missing link or links in documentation object 'package.Rd':
'../doc/package.pdf'
Is there a better way of linking from man to vignette? or it is not correct to do so? As the pdf can contain more graphical information, it seems desirable to be able to link to it.
If you use pkgdown to make a website out of your package, then you can directly link to the url of the specific vignette.
Or you can just write
Run \code{vignette("NAME_OF_YOUR_VIGNETTE", package = "NAME_OF_YOUR_PACKAGE")} to see the corresponding vignette.
What is the proper way, to include a static PDF file as a "vignette" in a CRAN package as of R 3.0?
The trick described in this document of using an empty stub Rnw does not seem to work in R 3.0. The document suggests that there is now a better way based on \VignetteEngine{} but it's not quite clear how this works for static PDF files.
With R.rsp (>= 1.19.0) you can include a static PDF 'vignettes/main.pdf' by adding a tiny 'vignettes/main.pdf.asis' text file that contains:
%\VignetteIndexEntry{My amazing package}
%\VignetteEngine{R.rsp::asis}
and make sure to have:
Suggests: R.rsp
VignetteBuilder: R.rsp
in your package's DESCRIPTION file. This also works for static HTML vignettes. This is also explained in one of the R.rsp vignettes.
This works with a plain LaTeX trick as described in in this blog post.
I recently switched to doing this with the current R version (i.e. now 3.6.0), see this wrapper .Rnw file which contains just:
\documentclass{article}
\usepackage{pdfpages}
%\VignetteIndexEntry{Using Annoy in C++}
%\VignetteKeywords{Rcpp, Annoy, R, Cpp, Approximate Nearest Neighbours}
%\VignettePackage{RcppAnnoy}
\begin{document}
\includepdf[pages=-, fitpaper=true]{UsingAnnoyInCpp.pdf}
\end{document}
The advantage is that this uses Sweave for a completely traditional vignette build, and imposes no additional dependencies whatsover.
UPDATE 2014-06-08: For a better solution to including static PDFs and HTML files in an R package, see my other answer in this thread on how to use R.rsp (>= 0.19.0) and its R.rsp::asis vignette engine.
All you need is a <name>.Rnw file with a name matching your static <name>.pdf file, e.g.
vignettes/
static.pdf
static.Rnw
where <name>.Rnw (here static.Rnw) is a minimal valid Sweave file, e.g.
%\VignetteIndexEntry{<title to be displayed on the R vignette index page>}
\documentclass{article}
\begin{document}
\end{document}
This vignette source file (<name>.Rnw) tricks R CMD build to build it, i.e. R's tools::buildVignettes() will first Sweave <name>.Rnw into <name>.tex as usual. However, due to how buildVignettes() is designed it will detect our static <name>.pdf file as already being created by the Sweave engine and therefore it will not compile that dummy TeX file into a PDF file (which would overwrite our static file).
What is important to understand is that (i) vignettes are "build" during R CMD build, (ii) and when built they are copied over to the inst/doc/ directory (created if missing) of the built package. Also, (iii) the vignettes/ directory will not be part of the build package, i.e. <pkgname>_<version>.tar.gz file. So, make sure to look in inst/doc/.
So, to be clear here, using a dummy <name>.Rnw could be considered a hack that may break if someone decides to prevent against this strategy. However, if that happens, it is fully possible to create a non-Sweave vignette engine which sole purpose is to compile a <name>.pdf file into a ... <name>.pdf file. This is valid and possible due to the non-Sweave support added in R (>= 3.0.0). I've been considering adding such engine to the R.rsp package, e.g. \VignetteEngine{R.rsp::StaticPDF}. With that you would not even have to have that dummy Rnw file - only the PDF file.
Hope this helps
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.