The R Project SVN R

% File src/library/tools/man/buildVignette.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2014 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 character; an optional package in which to find
    the vignette engine.}
  \item{encoding}{the encoding to assume for the file.  If not specified, it will
    be inferred from the file contents.}
  \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, it will be loaded before the vignette
  is processed, and will be used as the default package 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}