Enforce PDF package vignette with knitr

[January]

I have a vignette for my package which compiles to a nice PDF when compiled with Rscript -e 'rmarkdown::render("tmod.rmd")'. When I compile and install the package, start R and type vignette("mypackagename"), a browser window opens with ugly looking HTML, without a title, without a table of contents and without references. Anyway, I don't want an HTML vignette; I want a PDF.

However, if I compile the vignette manually to pdf before creating the package, it shows up just fine.

What went wrong? Why is my PDF not generated automatically when I compile the package?

In the markdown file header, I have

---
title: "foo foo foo"
author: "Foofooary Finer"
date: "`r Sys.Date()`"
output:
  pdf_document:
vignette: >
  %\VignetteIndexEntry{FooFoo}
  %\VignetteKeyword{foo}
  %\VignetteEngine{knitr::knitr}
  %\SweaveUTF8
  \usepackage[utf8](inputenc)
abstract: |
  foo foo foo foo foo
toc: yes
bibliography: bibliography.bib
---

In the package DESCRIPTION file, I have

VignetteBuilder: knitr
Suggests: knitr

[Yihui Xie]

Use the vignette engine knitr::rmarkdown instead of knitr::knitr.

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name

[January]

Magic. Thanks, indeed, it works. But now I am confused: why? 

Or, a better question: where can I find it documented?

> library(knitr)

> library(tools)

> names(vignetteEngine(package = 'knitr'))

[1] "knitr::rmarkdown"              "knitr::docco_classic_notangle" "knitr::docco_linear_notangle"  "knitr::knitr"                 

[5] "knitr::docco_classic"          "knitr::rmarkdown_notangle"     "knitr::knitr_notangle"         "knitr::docco_linear" 

> ?rmarkdown

No documentation for ‘rmarkdown’ in specified packages and libraries:

you could try ‘??rmarkdown’

> ?"knitr::rmarkdown"

No documentation for ‘knitr::rmarkdown’ in specified packages and libraries:

you could try ‘??knitr::rmarkdown’

best,

j.

[Yihui Xie]

You are right -- there isn't much documentation about it. There is a
help page ?knitr::vignette_engines, but it didn't explain what each
vignette engine does.

knitr::knitr uses R Markdown v1 to process .Rmd vignettes, and
knitr::rmarkdown uses R Markdown v2
(http://rmarkdown.rstudio.com/authoring_migrating_from_v1.html).

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name

> --
> You received this message because you are subscribed to the Google Groups
> "knitr" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to knitr+un...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[January]

> knitr::knitr uses R Markdown v1 to process .Rmd vignettes, and
> knitr::rmarkdown uses R Markdown v2
> (http://rmarkdown.rstudio.com/authoring_migrating_from_v1.html).

As an outsider -- someone who did not follow Sweave / knitr and who was just using old timey LaTeX until recently -- I think there is, for an uninformed user, a bit of a confusion around what is the document language (markdown, latex, latex/sweave, xml/html even), and what is the file output format (dvi, postscript, pdf, doc, html/css). 

Here was how I understood the world:

1) there is "output" in the header. It clearly specifies what the output is supposed to be; pdf_document in this case.

2) there is this mysterious engine thing that either uses knitr::knitr or maybe knitr::rmarkdown.  Well, it is markdown in any case, isn't it? After all, I did specify the output as "pdf_document", didn't I? I should follow The Book, shouldn't I?

Also, rmarkdown can produce anything from a markdown file, so I did not see a connection between PDF output and using knitr::rmarkdown. 

Do I understand the world correctly now -- the "output" option is honored only by knitr::rmarkdown, while knitr::knitr ignores it?

All the best,

j.

[Yihui Xie]

Again, you are right. knitr::knitr and R Markdown v1 do not understand
R Markdown v2. Almost everything you mentioned was specific to v2.
When you use R Markdown, chances are that you mean v2. I cannot wipe
out the history of Sweave, .Rnw/LaTeX, or R Markdown v1 in one day.
That is probably the source of confusion.

BTW, the next time when you cross-post, please do cross-reference to
make it easier for future users to find answers and explanations:
http://stackoverflow.com/q/30936969/559676 Thanks!

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name

[January]

Understood! I put a link on stackoverflow (in this question: http://stackoverflow.com/questions/30936969/enforce-pdf-package-vignette-with-knitr).

Yes, this is the nagging feeling I have when reading knitr / rmarkdown / Sweave documentation is that this is a construction that has been gradually build over many years, and without knowing the history (for example, how v1 used to work, what were the problems with Sweave etc.) makes it hard for a newcomer. I have seen it so many times in different areas of science...

All the best, and thanks for the extensive explanations,

j.

[Roger Day]

Hi Yihui,

Using the RStudio Build and Reload button,

my vignette builds and appears locally in the project home folder, 

but not in the newly built and reloaded package in the system library.

Eventually I found the answer at 

http://r-pkgs.had.co.nz/vignettes.html:

adding both knitr and rmarkdown to Suggests,

and installing with: devtools::install(build_vignettes = TRUE).

It would be good to disseminate this tidbit of information. 

Your mention of R markdown v2 has me confused.

Looking at www.github.com/rStudio/rmarkdown,

the latest version is 1.0.9014 , bumped as of 10 days ago--

over a year since your post.

So where and what is Rmarkdown v2?

Thanks for all the great resources you've create for our community!

[Yihui Xie]

I just filed an issue to the RStudio IDE team to see if it is possible
to change the button "Build & Reload" to "Install & Reload" because
the former currently does R CMD INSTALL, and we should add a real
button "Build & Reload" that does R CMD build, which will build your
vignettes by default.

The help page ?knitr::vignette_engines mentioned the requirement of
rmarkdown in Suggests, but I guess it is not easy to find this piece
of information.

R Markdown v2 actually means rmarkdown. This was to discriminate from
an older version of R Markdown, which we call v1 and is essentially
the markdown package. In short, R Markdown v2 = rmarkdown, and R
Markdown v1 = markdown. The numbers 1 and 2 do not really imply
package versions. I agree that is a bit confusing.

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name