So I have finally switched to knitr for doing my vignettes. The result is satisfactory, but the process was not entirely painless.

• The command to run instead of “R CMD Sweave foo.Rnw” is

  Rscript -e 'rmarkdown::render("foo.rmd")'

• I think that the concept of writing a package which has the main purpose to generate documentation in literate programming without providing mandatory documentation (such as list of options) within the package itself, referring instead to the online resources is beautifully subversive.

• Knitr in the current R version requires pandoc X.Y.Z, while Ubuntu has X.Y.(Z-1). It was necessary to download the deb package from the pandoc site and install it manually.

• To use knitr in vignettes, you need to add `VignetteBuilder:knitr` to your `DESCRIPTION` file.

• I was confused at first as to what to do the old vignette header (the lines that start with “%Vignette…”). The markdown header is different. Turns out you have to include these lines in the markdown header (Kill me, but I have no idea why there is a “>” behind “vignette:” or “|” behind “abstract:”. Knitr produces neat results, but it is one of the most confusing packages I have ever encountered.):

                  ---
                  title: "FOO: the fooly of foology"
                  author: "January Weiner"
                  date: "`r Sys.Date()`"
                  output: 
                    pdf_document:
                  vignette: >
                    %VignetteIndexEntry{Foo}
                    %VignetteKeyword{foo}
                    %VignetteKeyword{foology}
                    %VignetteEngine{knitr::rmarkdown}
                    %SweaveUTF8
                    usepackage[utf8](inputenc)
                  abstract: |
                    Foo foo foo foo. Foo foo, foo foo foo, foo.
                  toc: yes
                  bibliography: bibliography.bib
                  ---
   

• <>= becomes “`{r label, fig.width=5, fig.height=5}. Also, any character argument to options must be in quotes.

• I have no idea why fig.width=5 works, but opt.chunk$set(fig.width=5) doesn’t and at this point I don’t care to ask.

• I had a nightmarish forensic experience trying to figure out why my figures don’t get updated, where is the cache and some other things. Turns out that if you provide a symbolic link to an rmd file to knitr, it will change to the directory to where the original is. Which is not the same behavior as in the case of Sweave.

• It turns out that some options are valid for HTML, but not PDF, and vice versa, and you don’t get a warning. Also, it’s not mentioned in the documentation. Why? Because f— you, that’s why. For example, I spent half an hour trying to change the theme of a PDF vignette, after which it turned out that the theme option is not valid for PDFs. There was a table somewhere showing which options can be used when, but I lost the link and can’t find it in the documentation.

• I haven’t found out how to change the font size if generating pdf_document (my favorite). Update: I have found out that it is not possible.

• Also, no idea how to prevent breaking code small chunks between pages, which really, really should not happen.

• At first I specified the vignette engine to be knitr::knitr, but apparently this produces only (botched) HTML vignette (botched: no title, no author, no references). To generate neat, honest-to-Knuth PDF via pandoc and LaTeX, one should use knitr::rmarkdown, although that is not documented anywhere.

  %VignetteEngine{knitr::rmarkdown}