Sweave             package:utils             R Documentation(latin1)

Automatic Generation of Reports

Description:

     '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.

Usage:

     Sweave(file, driver = RweaveLatex(),
            syntax = getOption("SweaveSyntax"), ...)

     Stangle(file, driver = Rtangle(),
             syntax = getOption("SweaveSyntax"), ...)

Arguments:

    file: Name of Sweave source file.

  driver: The actual workhorse, see details below.

  syntax: An object of class 'SweaveSyntax' or a character string with
          its name. The default installation provides
          'SweaveSyntaxNoweb' and 'SweaveSyntaxLatex'.

     ...: Further arguments passed to the driver's setup function.

Details:

     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.

     'Sweave' combines the documentation and code chunks together (or
     their output) into a single document.  'Stangle' extracts only the
     code from the Sweave file creating a valid S source file (that can
     be run using 'source').  Code inside '\Sexpr{}' statements is
     ignored by 'Stangle'.

     'Stangle' is just a frontend to 'Sweave' using a simple driver by
     default, which discards the documentation and concatenates all
     code chunks the current S engine understands.

Hook Functions:

     Before each code chunk is evaluated, a number of hook functions
     can be executed.  If 'getOption("SweaveHooks")' is set, it is
     taken to be a collection of hook functions. For each logical
     option of a code chunk ('echo', 'print', ...) a hook can be
     specified, which is executed if and only if the respective option
     is 'TRUE'. Hooks must be named elements of the list returned by
     'getOption("SweaveHooks")' and be functions taking no arguments. 
     E.g., if option '"SweaveHooks"' is defined as 'list(fig = foo)',
     and '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 'clean' that removes all objects in the
     global environment.  Then all code chunks with 'clean = TRUE'
     would start operating on an empty workspace.

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.

Author(s):

     Friedrich Leisch

References:

     Friedrich Leisch: Dynamic generation of statistical reports using
     literate data analysis. In W. Haerdle and B. Roenz, editors,
     Compstat 2002 - Proceedings in Computational Statistics, pages
     575-580. Physika Verlag, Heidelberg, Germany, 2002. ISBN
     3-7908-1517-9.

     Friedrich Leisch: Sweave User Manual, 2008
      <URL: http://www.stat.uni-muenchen.de/~leisch/Sweave>

See Also:

     'RweaveLatex', 'Rtangle'

Examples:

     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")

