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

[Martin Morgan]

On 08/04/2015 03:06 AM, Vincent Carey wrote:
> Thanks for all input.  Henrik's comments deserve to be in WRE or developer
> doc for bioc, IMHO.

yes, was there any attempt to get something more in WRE? Martin

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


-- 
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M1 B861
Phone: (206) 667-2793