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]]
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
