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

Am I correct that this is not allowed?  I have an old Sweave vignette
and a newer Rmd vignette in gwascat but do not see how to build
so that both vignettes are properly situated in the installed doc folder.
The WRE manual doesn't address multiple builders.  So I am planning
to translate the older one to Rmd.

        [[alternative HTML version deleted]]

From: "Sean Davis" <seandavi at gmail.com>
To: "Vincent Carey" <stvjc at channing.harvard.edu>
Cc: bioc-devel at r-project.org
Sent: Monday, August 3, 2015 4:01:58 PM
Subject: Re: [Bioc-devel] vignettes with different builders in one package?

Hi, Vince.

It seems like knitr should be able to build a sweave vignette,
particularly
if the stuff in the << >> has been converted from sweave to knitr
format?
It might be easier to do that than to convert the original to
Rmarkdown.

Sean



On Mon, Aug 3, 2015 at 6:57 PM, Vincent Carey
<stvjc at channing.harvard.edu>
wrote:

Am I correct that this is not allowed?  I have an old Sweave
vignette
and a newer Rmd vignette in gwascat but do not see how to build
so that both vignettes are properly situated in the installed doc
folder.
The WRE manual doesn't address multiple builders.  So I am planning
to translate the older one to Rmd.

        [[alternative HTML version deleted]]

	[[alternative HTML version deleted]]

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)

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