21

I use knitr and rmarkdown to write vignettes for R packages. Thanks to the magic of pandoc it is easy to turn these documents into a variety of formats. I would like to take advantage of this by offering vignettes as both HTML and PDF. There is support from rmarkdown to specify parameters for multiple output formats in the documents metadata block. For example, I might have something like this:

output:
  html_document:
    standalone: true
    smart: true
    normalize: true
    toc: true
    highlight: tango
    self-contained: true
    theme: cerulean
  pdf_document:
    toc: true
    highlight: tango
geometry: margin=2cm
documentclass: article
classoption: a4paper

From the R command-line I can use rmarkdown::render to build either one or both of the output documents without difficulties. However, when the package is build only the output format that is listed first is used. I have tried to include a Makefile that builds both by including something along the lines of

all: %.Rmd
    $(R_HOME)/bin/Rscript -e "rmarkdown::render('$*.Rmd', 'all')"

and that is successful in the sense that all output files are generated but only one of them is recognised as vignette by R. To get additional outputs included in docs/ they have to be added to .install_extras. While that ensures they are accessible via the HTML index they are listed separately from the vignettes and and I don't think they can be accessed from within R (via vignette()).

Is there a better way (or any automated way) to do this?

Peter Humburg
  • 550
  • 5
  • 15
  • 2
    FYI, this is the same issue as https://github.com/yihui/knitr/issues/1051 – Yihui Xie Jul 05 '15 at 05:14
  • Thanks @Yihui. Good to know that you are looking into it. Have you had a chance to investigate yet? In particular how compatible that is with R CMD check seems like an important question regarding the feasibility of this. – Peter Humburg Jul 05 '15 at 10:32
  • You could try including lines in your make to switch from html to pdf. Generate the vignette, use `sed` to switch from html to pdf, re-generate, and switch back. – Josh Aug 04 '15 at 00:34
  • @Josh, the problem is that R insists that each vignette source file should produce exactly one output file. It is possible to generate additional outputs and even get them copied to `docs/` by listing them in *.install_extras* but they aren't recognised as vignettes as such. – Peter Humburg Aug 04 '15 at 10:50
  • You could make a copy of your vignette then. Have your original output html, and create a *.pdf.Rmd version. The Makefile would be a good place for this. – Josh Aug 04 '15 at 10:52

1 Answers1

2

Two things:

  1. you could 'include' the common content and have two source files with different headers, or,

  2. if the extra vignette really doesn't show up in the index, write your own. From Writing R extensions: "At install time an HTML index for all vignettes in the package is automatically created from the \VignetteIndexEntry statements unless a file index.html exists in directory inst/doc. This index is linked from the HTML help index for the package." The vignette index entry might also be a clue to having your probably identically named vignettes be recognized as distinct.

Jack Wasey
  • 3,360
  • 24
  • 43