blob: d4f6654a453f1fa97f313d6d02abb1627062b37f [file] [log] [blame]
% 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}