% File src/library/utils/man/Sweave.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2022 R Core Team
% Distributed under GPL 2 or later

\name{Sweave}
\alias{Sweave}
\alias{Stangle}
\alias{SweaveSyntaxLatex}
\alias{SweaveSyntaxNoweb}
\encoding{UTF-8}
\title{Automatic Generation of Reports}
\description{
  \code{Sweave} provides a flexible framework for mixing text and R/S code
  for automatic report generation.  The basic idea is to replace the
  code with its output, such that the final document only contains the
  text and the output of the statistical analysis: however, the source
  code can also be included.
}
\usage{
Sweave(file, driver = RweaveLatex(),
       syntax = getOption("SweaveSyntax"), encoding = "", ...)

Stangle(file, driver = Rtangle(),
        syntax = getOption("SweaveSyntax"), encoding = "", ...)
}
\arguments{
  \item{file}{Path to Sweave source file.  Note that this can be
    supplied without the extension, but the function will only proceed
    if there is exactly one Sweave file in the directory whose
    basename matches \code{file}.}
  \item{driver}{the actual workhorse, (a function returning) a named
    \code{\link{list}} of five functions; for details, see Section 5 of the
    \sQuote{Sweave User Manual} available as \code{vignette("Sweave")}.}
  \item{syntax}{\code{NULL} or an object of class \code{"SweaveSyntax"} or
    a character string with its name.
    See the section \sQuote{Syntax Definition}.}
  \item{encoding}{The default encoding to assume for \code{file}.}
  \item{\dots}{further arguments passed to the driver's setup function.
    See \code{\link{RweaveLatexSetup}} and \code{\link{RtangleSetup}},
    respectively, for the arguments of the default drivers.}
}

\details{
  An Sweave source file contains both text in a markup language (like
  \LaTeX) and \R (or S) code.  The code gets replaced by its output (text or
  graphs) in the final markup file.  This allows a report to be re-generated
  if the input data change and documents the code to reproduce the
  analysis in the same file that also produces the report.

  \code{Sweave} combines the documentation and code chunks (or
  their output) into a single document.  \code{Stangle} extracts only
  the code from the Sweave file creating an \R source file that can be
  run using \code{\link{source}}.  (Code inside \code{\\Sexpr\{\}}
  statements is ignored by \code{Stangle}.)
  
  \code{Stangle} is just a wrapper to \code{Sweave} specifying a
  different default driver.  Alternative drivers can be used and are
  provided by various contributed packages.

  Environment variable \env{SWEAVE_OPTIONS} can be used to override the
  initial options set by the driver: it should be a comma-separated set
  of \code{key=value} items, as would be used in a \samp{\\SweaveOpts}
  statement in a document.

  If the \code{encoding} is unspecified (the default),
  \emph{non-ASCII} source files must contain a line of the form
\preformatted{  \usepackage[foo]{inputenc}}
  (where \samp{foo} is typically \samp{latin1}, \samp{latin2}, \samp{utf8} or
  \samp{cp1252} or \samp{cp1250}) or a comment line
  \preformatted{  \%\SweaveUTF8}
  to declare UTF-8 input (the default encoding assumed by pdfTeX since 2018),
  or they will give an error.
  Re-encoding can be turned off completely with argument
  \code{encoding = "bytes"}.
}

\section{Syntax Definition}{
  Sweave allows a flexible syntax framework for marking
  documentation and text chunks. The default is a noweb-style syntax, as
  alternative a \LaTeX-style syntax can be used.  (See the user manual for
  further details.)

  If \code{syntax = NULL} (the default) then the available syntax
  objects are consulted in turn, and selected if their \code{extension}
  component matches (as a regexp) the file name.  Objects
  \code{SweaveSyntaxNoweb} (with \code{extension = "[.][rsRS]nw$"}) and
  \code{SweaveSyntaxLatex} (with \code{extension = "[.][rsRS]tex$"}) are
  supplied, but users or packages can supply others with names matching
  the pattern \code{SweaveSyntax.*}.
}

\author{
  Friedrich Leisch and R-core.
}

\references{
  Friedrich Leisch (2002)
  Dynamic generation of statistical reports using literate data analysis.
  In W. \enc{Härdle}{Haerdle} and B. \enc{Rönz}{Roenz}, editors,
  \emph{Compstat 2002 - Proceedings in Computational Statistics},
  pages 575--580. Physika Verlag, Heidelberg, Germany, ISBN 3-7908-1517-9.
}

\seealso{
  \sQuote{\href{../doc/Sweave.pdf}{Sweave User Manual}}, a vignette in
  the \pkg{utils} package.

  \code{\link{RweaveLatex}}, \code{\link{Rtangle}}.
  Alternative Sweave drivers are in, for example, packages
  \pkg{weaver} (Bioconductor), \CRANpkg{R2HTML}, and \CRANpkg{ascii}.

  \code{tools::\link[tools]{buildVignette}} to process source files
  using Sweave or alternative vignette processing engines.
}

\examples{
testfile <- system.file("Sweave", "Sweave-test-1.Rnw", package = "utils")
\dontshow{oldwd <- setwd(tempdir()) # so we will write only to a temp directory}

## enforce par(ask = FALSE)
options(device.ask.default = FALSE)

## create a LaTeX file - in the current working directory, getwd():
Sweave(testfile)

## This can be compiled to PDF by
## tools::texi2pdf("Sweave-test-1.tex")

## or outside R by
##
## 	R CMD texi2pdf Sweave-test-1.tex
## on Unix-alikes which sets the appropriate TEXINPUTS path.
##
## On Windows,
##      Rcmd texify --pdf Sweave-test-1.tex
## if MiKTeX is available.

## create an R source file from the code chunks
Stangle(testfile)
## which can be sourced, e.g.
source("Sweave-test-1.R")

\dontshow{
if(!interactive()) unlink("Sweave-test-1*")
setwd(oldwd)
}
}
\keyword{utilities}