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

[Vincent Carey]

Thanks for all input.  Henrik's comments deserve to be in WRE or developer
doc for bioc, IMHO.

On Tue, Aug 4, 2015 at 3:02 AM, Henrik Bengtsson <henrik.bengtsson at ucsf.edu>
wrote:

> 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]]