| % File src/library/tools/man/buildVignette.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{buildVignette} |
| \alias{buildVignette} |
| \title{Build One Vignette} |
| \description{ |
| Run \code{\link{Sweave}} (or other custom weave function) |
| \code{\link{texi2dvi}}, and/or \code{\link{Stangle}} |
| (or other custom tangle function) on one vignette. |
| |
| This is the workhorse of \command{R CMD Sweave}. |
| } |
| \usage{ |
| buildVignette(file, dir = ".", weave = TRUE, latex = TRUE, tangle = TRUE, |
| quiet = TRUE, clean = TRUE, keep = character(), |
| engine = NULL, buildPkg = NULL, encoding, ...) |
| } |
| \arguments{ |
| \item{file}{character; the vignette source file.} |
| \item{dir}{character; the working directory in which the intermediate and |
| output files will be produced.} |
| \item{weave}{logical; should weave be run?} |
| \item{latex}{logical; \link{texi2pdf} be run if weaving produces a \file{.tex} file?} |
| \item{tangle}{logical; should tangle be run?} |
| \item{quiet}{logical; run in quiet mode?} |
| \item{clean}{logical; whether to remove some newly created, often |
| intermediate, files. See details below.} |
| \item{keep}{a list of file names to keep in any case when cleaning. Note |
| that \dQuote{target} files are kept anyway.} |
| \item{engine}{\code{NULL} or character; name of vignette engine to |
| use. Overrides any \code{\\VignetteEngine\{\}} markup in the vignette.} |
| \item{buildPkg}{\code{NULL} or a character vector; optional packages |
| in which to find the vignette engine.} |
| \item{encoding}{the encoding to assume for the file. If not |
| specified, it will be read if possible from the file's contents. |
| Note that if the vignette is part of a package, |
| \code{\link{buildVignettes}} reads the package's encoding from the |
| \file{DESCRIPTION} file but this function does not.} |
| \item{...}{Additional arguments passed to weave and tangle.} |
| |
| } |
| \details{ |
| This function determines the vignette engine for the vignette (default |
| \code{utils::Sweave}), then weaves and/or tangles the vignette using |
| that engine. Finally, if \code{clean} is \code{TRUE}, newly created |
| intermediate files (non \dQuote{targets}, where these depend on the engine, |
| etc, and not any in \code{keep}) will be deleted. If \code{clean} is |
| \code{NA}, and \code{weave} is true, newly created intermediate output |
| files (e.g., \file{.tex}) will not be deleted even if a \file{.pdf} |
| file has been produced from them. |
| |
| If \code{buildPkg} is specified, those packages will be loaded before |
| the vignette is processed and will be used as the default packages in |
| the search for a vignette engine, but an explicitly specified package |
| in the vignette source (e.g., using |
| \code{\\VignetteEngine\{utils::Sweave\}} to specify the \code{Sweave} |
| engine in the \pkg{utils} package) will override it. In contrast, if |
| the \code{engine} argument is given, it will override the vignette |
| source. |
| } |
| \value{ |
| A character vector naming the files that have been produced. |
| } |
| \author{ |
| Henrik Bengtsson and Duncan Murdoch |
| } |
| \seealso{ |
| \code{\link{buildVignettes}} for building all vignettes in a package. |
| } |
| \keyword{documentation} |