[Bioc-devel] vignettes with different builders in one package?

[Henrik Bengtsson]

You can mix any type and number of vignette formats in a package. What
vignette engine is used is solely specified by the
%\VignetteEngine{<pkg>::<engine>} markup string. You don't need to specify
this for the default Sweave format, but you can as:

%\VignetteEngine{utils::Sweave}

For your knitr vignette you'd use:

%\VignetteEngine{knitr::knitr}

The <engine> part of the specification is the registered engine name and
*not* a function name; in the above to cases this just happens to both. For
example,

%\VignetteEngine{R.rsp::asis}

specifies engine 'asis' (for static pre-built PDF and HTML vignettes) of
the vignette builder package R.rsp, but there is no asis() function in that
package.

(BTW, the % is a remnant from the time when everything was LaTeX based and
when it was used to specify a LaTeX comment. However it is still needed,
because it is part of the markup syntax. Ideally it would not have been
needed in non-LaTeX-based formats, but it was kept due to tight deadlines
on the design when this was first implemented.)

The filename extension controls nothing (except that it is used as a
fallback for the default Sweave engine for backward compatible reasons).
However, each vignette engine recognizes a given filename pattern so you
need to use an extension that is recognized by the engine of interest.
Engines can recognize the same patterns/extensions, e.g. Sweave and knitr
both recognizes *.Rnw.  When a package is built, each engine is first asked
what files it is interested in (think dir(pattern=pattern)) and among those
a match for %\VignetteEngine{...} is then searched. If no match, then the
next registered engine is checked. If a march, then the engine build the
vignette.  What engines are registered are controlled by what
vignette-builder packages are used/loaded (see VignetteBuilder below).

You can test build a single vignette manually using:

tools::buildVignette(pathname)

That will decide on the engine based on the %\VignetteEngine{...} markup.
Don't forget to load the vignette builder package first so its engines are
registered, e.g. library(knitr). That's a good way to test it without
having to use R CMD build (which is when all vignette templates in
vignettes/ are built and moved together with the vignette products to
inst/doc/).

Finally, for R CMD build to work, you need:

VignetteBuilder: utils, knitr

and specify those vignette builder packages also under Suggests (unless
they're already under Depends or Imports) in your package's DESCRIPTION
file.

Hope this clarifies it further

Henrik
(I wrote a fair chunk of the original code for dealing with any type of
vignettes)

	[[alternative HTML version deleted]]