\inputencoding{latin1}
\HeaderA{Sweave}{Automatic Generation of Reports}{Sweave}
\aliasA{Stangle}{Sweave}{Stangle}
\aliasA{SweaveSyntaxLatex}{Sweave}{SweaveSyntaxLatex}
\aliasA{SweaveSyntaxNoweb}{Sweave}{SweaveSyntaxNoweb}
\keyword{utilities}{Sweave}
\begin{Description}\relax
\code{Sweave} provides a flexible framework for mixing text and S code
for automatic report generation.  The basic idea is to replace the S
code with its output, such that the final document only contains the
text and the output of the statistical anlysis.
\end{Description}
\begin{Usage}
\begin{verbatim}
Sweave(file, driver = RweaveLatex(),
       syntax = getOption("SweaveSyntax"), ...)

Stangle(file, driver = Rtangle(),
        syntax = getOption("SweaveSyntax"), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] Name of Sweave source file.
\item[\code{driver}] The actual workhorse, see details below.
\item[\code{syntax}] An object of class \code{SweaveSyntax} or a character
string with its name. The default installation provides
\code{SweaveSyntaxNoweb} and \code{SweaveSyntaxLatex}.
\item[\code{...}] Further arguments passed to the driver's setup function.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Automatic generation of reports by mixing word processing markup (like
latex) and S code.  The S 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 together
(or their output) into a single document.  \code{Stangle} extracts only
the code from the Sweave file creating a valid S source file (that can
be run using \code{\LinkA{source}{source}}).  Code inside \code{\bsl{}Sexpr\{\}}
statements is ignored by \code{Stangle}.

\code{Stangle} is just a frontend to \code{Sweave} using a simple
driver by default, which discards the documentation and concatenates
all code chunks the current S engine understands.
\end{Details}
\begin{Section}{Hook Functions}
Before each code chunk is evaluated, a number of hook functions can be
executed.  If \code{getOption("SweaveHooks")} is set, it is taken to be
a collection of hook functions. For each logical option of a code chunk
(\code{echo}, \code{print}, \ldots) a hook can be specified, which is
executed if and only if the respective option is \code{TRUE}. Hooks must
be named elements of the list returned by
\code{getOption("SweaveHooks")} and be functions taking no
arguments.  E.g., if option \code{"SweaveHooks"} is defined as
\code{list(fig = foo)}, and \code{foo} is a function, then it would be
executed before the code in each figure chunk. This is especially useful
to set defaults for the graphical parameters in a series of figure
chunks.

Note that the user is free to define new Sweave options and associate
arbitrary hooks with them.  E.g., one could define a hook function for
option \code{clean} that removes all objects in the global
environment.  Then all code chunks with \code{clean = TRUE} would start
operating on an empty workspace.
\end{Section}
\begin{Section}{Syntax Definition}
Sweave allows a very 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
details.
\end{Section}
\begin{Author}\relax
Friedrich Leisch
\end{Author}
\begin{References}\relax
Friedrich Leisch: Sweave User Manual, 2002\\
\url{http://www.ci.tuwien.ac.at/~leisch/Sweave}

Friedrich Leisch: Dynamic generation of statistical reports using
literate data analysis. In W. Härdle and
B. Rönz, editors, Compstat 2002 - Proceedings in Computational
Statistics, pages 575--580. Physika Verlag, Heidelberg, Germany,
2002. ISBN 3-7908-1517-9.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{RweaveLatex}{RweaveLatex}}, \code{\LinkA{Rtangle}{Rtangle}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
testfile <- system.file("Sweave", "Sweave-test-1.Rnw", package = "utils")

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

## create a LaTeX file
Sweave(testfile)

## This can be compiled to PDF by
## Not run: tools::texi2dvi("Sweave-test-1.tex", pdf=TRUE)
## or outside R by
## R CMD texi2dvi Sweave-test-1.tex
## which sets the appropriate TEXINPUTS path.

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


\end{ExampleCode}
\end{Examples}

