\name{QA}
\alias{QA}
\alias{checkAssignFuns}
\alias{checkDocArgs}
\alias{checkDocStyle}
\alias{checkMethods}
\alias{print.checkAssignFuns}
\alias{print.checkDocArgs}
\alias{print.checkDocStyle}
\alias{print.checkMethods}
\title{QA Checks for R Code and/or Documentation}
\description{
  Functions for performing various quality checks.
}
\usage{
checkAssignFuns(package, dir, lib.loc = NULL)
checkDocArgs(package, dir, lib.loc = NULL)
checkDocStyle(package, dir, lib.loc = NULL)
checkMethods(package, dir, lib.loc = NULL)
}
\arguments{
  \item{package}{a character string naming an installed package.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This should contain the subdirectories \code{R}
    (for R code) and \file{man} with \R documentation sources (in Rd
    format).  Only used if \code{package} is not given.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
}
\details{
  \code{checkAssignFuns} checks whether assignment functions in the
  package R code have their final argument named \code{value}.
  
  \code{checkDocArgs} checks, for all Rd files in a package, whether all
  arguments shown in the usage sections of the Rd file are documented in
  its arguments section.  It also reports duplicated entries in the
  arguments section.

  \code{checkDocStyle} investigates how (S3) methods are shown in the
  usages of the Rd files in a package.  It reports if methods are shown
  along with their generic, which typically causes problems for the
  documentation of the primary argument of the generic.  It also finds
  the methods shown by their full name (rather than that of the generic
  using the Rd \code{\\method} markup).

  \code{checkMethods} checks whether all methods defined in the package
  R code have all arguments of the corresponding generic, with
  positional arguments of the generics in the same positions for the
  method.  The generics are sought first in the given package and then
  in the base package.  The rules when \code{\dots} is involved are
  subtle: see the source code.

  If using an installed package, the checks needing access to all R
  objects of the package will load the package (unless it is the base
  package), after possibly detaching an already loaded version of the
  package.
}
\value{
  The functions return objects of class the same as the respective
  function names containing the information about problems detected.
  There is a \code{print} method for nicely displaying the information
  contained in such objects.
}
\section{Warning}{
  These functions are still experimental.  Both names, interfaces and
  values might change in future versions.
}
\keyword{utilities}
\keyword{documentation}
\name{Rtangle}
\alias{Rtangle}
\alias{RtangleSetup}
\title{R Driver for Stangle}
\description{
  A driver for \code{\link{Stangle}} that extracts R code chunks.
}
\usage{
Rtangle()
RtangleSetup(file, syntax, output=NULL, annotate=TRUE, split=FALSE,
             prefix=TRUE, quiet=FALSE)
}
\arguments{
  \item{file}{Name of Sweave source file.}
  \item{syntax}{An object of class \code{SweaveSyntax}.}
  \item{output}{Name of output file, default is to remove extension \file{.nw},
    \file{.Rnw} or \file{.Snw} and to add extension \file{.R}. Any
    directory names in \code{file} are also removed such that the output
    is created in the current working directory.}
  \item{annotate}{By default, code chunks are seperated by comment
    lines specifying the names and numbers of the code chunks. If
    \code{FALSE}, only the code chunks without any decorating comments
    are extracted.}
  \item{split}{Split output in single files per code chunk?}
  \item{prefix}{If \code{split=TRUE}, prefix the chunk labels by the
    basename of the input file to get output file names?}
  \item{quiet}{If \code{TRUE} all progress messages are suppressed.}
}
\author{Friedrich Leisch}
\references{
  Friedrich Leisch: Sweave User Manual, 2002\cr
  \url{http://www.ci.tuwien.ac.at/~leisch/Sweave}
}
\seealso{\code{\link{Sweave}}, \code{\link{RweaveLatex}}}
\keyword{utilities}

\name{RweaveLatex}
\alias{RweaveLatex}
\alias{RweaveLatexSetup}
\title{R/LaTeX Driver for Sweave}
\description{
  A driver for \code{\link{Sweave}} that translates R code chunks in
  LaTeX files.
}
\usage{
RweaveLatex()
RweaveLatexSetup(file, syntax, output=NULL, quiet=FALSE, debug=FALSE,
                 echo=TRUE, eval = TRUE, split=FALSE, stylepath=TRUE,
                 pdf=TRUE, eps=TRUE)
}
\arguments{
  \item{file}{Name of Sweave source file.}
  \item{syntax}{An object of class \code{SweaveSyntax}.}
  \item{output}{Name of output file, default is to remove extension
    \file{.nw}, \file{.Rnw} or \file{.Snw} and to add extension
    \file{.tex}. Any 
    directory names in \code{file} are also removed such that the output
    is created in the current working directory.}
  \item{quiet}{If \code{TRUE} all progress messages are suppressed.}
  \item{debug}{If \code{TRUE}, input and output of all code
    chunks is copied to the console.}
  \item{stylepath}{If \code{TRUE}, a hard path to the file \file{Sweave.sty}
    installed with this package is set, if \code{FALSE}, only
    \code{\\usepackage\{Sweave\}} is written. The hard path makes the
    TeX file less
    portable, but avoids the problem of installing the current
    version of \file{Sweave.sty} to some place in your TeX input path.
    The argument is ignored if a \code{\\usepackage\{Sweave\}} is
    already present in the Sweave source file.
  }
  \item{echo}{set default for option \code{echo}, see defails below.}
  \item{eval}{set default for option \code{eval}, see defails below.}
  \item{split}{set default for option \code{split}, see defails below.}
  \item{pdf}{set default for option \code{pdf}, see defails below.}
  \item{eps}{set default for option \code{eps}, see defails below.}
}
\section{Supported Options}{
  RweaveLatex supports the following options for code chunks (the values
  in parentheses show the default values):
  \describe{
    \item{echo:}{logical (\code{TRUE}). Include S code in the
      output file?}
    \item{eval:}{logical (\code{TRUE}). If \code{FALSE}, the code chunk is not
      evaluated, and hence no text or graphical output produced.}
    \item{results:}{character string (\code{verbatim}).
      If \code{verbatim}, the output of S commands is
      included in the verbatim-like Soutput environment. If
      \code{tex}, the output is taken to be already proper latex markup
      and included as is. If \code{hide} then all output is
      completely suppressed (but the code executed during the weave).}
    \item{print:}{logical (\code{FALSE})
      If \code{TRUE}, each expression in the
      code chunk is wrapped into a \code{print()} statement before evaluation,
      such that the values of all expressions become visible.}
    \item{term:}{logical (\code{TRUE}). If \code{TRUE}, visibility of values
      emulates an interactive R session: values of assignments are not
      printed, values of single objects are printed. If \code{FALSE},
      output comes only from explicit \code{\link{print}} or
      \code{\link{cat}} statements.}
    \item{split:}{logical (\code{FALSE}). If \code{TRUE}, text output is
      written to seperate files 
      for each code chunk.}
    \item{strip.white:}{logical (\code{TRUE}). If \code{TRUE}, blank
      lines at the beginning and end of output are removed.}
    \item{prefix:}{logical (\code{TRUE}). If \code{TRUE} generated filenames of
      figures and output have a common prefix.}
    \item{prefix.string:}{a character string, default is the name of the
      \file{.Snw} source file.}
    \item{include:}{logical (\code{TRUE}), indicating whether input
      statements for text output and includegraphics statements
      for figures should be auto-generated. Use \code{include=FALSE} if
      the output should appear in a different place than the code chunk
      (by placing the input line manually).}
    \item{fig:}{logical (\code{FALSE}), indicating whether the code
      chunk produces 
      graphical output. Note that only one figure per code chunk can be
      processed this way.}
    \item{eps:}{logical (\code{TRUE}), indicating whether EPS figures shall be
      generated. Ignored if \code{fig=FALSE}.} 
    \item{pdf:}{logical (\code{TRUE}), indicating whether PDF figures shall be
      generated. Ignored if \code{fig=FALSE}.}
    \item{width:}{numeric (6), width of figures in inch.}
    \item{height:}{numeric (6), height of figures in inch.}
  }
}
\author{Friedrich Leisch}
\references{
  Friedrich Leisch: Sweave User Manual, 2002\cr
  \url{http://www.ci.tuwien.ac.at/~leisch/Sweave}
}
\seealso{\code{\link{Sweave}}, \code{\link{Rtangle}}}
\keyword{utilities}
\name{Sweave}
\alias{Sweave}
\alias{Stangle}
\alias{SweaveSyntaxLatex}
\alias{SweaveSyntaxNoweb}
\title{Automatic Generation of Reports}
\description{
  \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. 
}
\usage{
Sweave(file, driver=RWeaveLatex(), syntax=getOption("SweaveSyntax"), ...)
Stangle(file, driver=RTangle(), syntax=getOption("SweaveSyntax"), ...)
}
\arguments{
  \item{file}{Name of Sweave source file.}
  \item{driver}{The actual workhorse, see details below.}
  \item{syntax}{An object of class \code{SweaveSyntax} or a character
    string with its name. The default installation provides
    \code{SweaveSyntaxNoweb} and \code{SweaveSyntaxLatex}.}
  \item{\dots}{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 to re-generate a report
  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{\link{source}}). Code inside \code{\\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.
}   
\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.
}
\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.
}
\author{Friedrich Leisch}
\references{
  Friedrich Leisch: Sweave User Manual, 2002\cr
  \url{http://www.ci.tuwien.ac.at/~leisch/Sweave}

  Friedrich Leisch: Dynamic generation of statistical reports using
  literate data analysis. Report 69, SFB ``Adaptive Information Systems
  and Modelling in Economics and Management Science'', March 2002.
}
\seealso{\code{\link{RweaveLatex}}, \code{\link{Rtangle}}}
\examples{
testfile <- file.path(.path.package("tools"),
                      "Sweave", "Sweave-test-1.Rnw")

## create a LaTeX file
Sweave(testfile)

## create an S source file from the code chunks
Stangle(testfile)
## which can be simply sourced
source("Sweave-test-1.R")
\testonly{unlink("Sweave-test-1*")}
}
\keyword{utilities}

\name{checkFF}
\alias{checkFF}
\alias{print.checkFF}
\title{Check Foreign Function Calls}
\usage{
checkFF(package, dir, file, lib.loc = NULL,
        verbose = getOption("verbose"))
}
\description{
  Performs checks on calls to compiled code from R code.  Currently only
  whether the interface functions such as \code{.C} and \code{.Fortran}
  are called with argument \code{PACKAGE} specified, which is highly
  recommended to avoid name clashes in foreign function calls.
}
\arguments{
  \item{package}{a character string naming an installed package.  If
    given, the installed R code of the package is checked.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This should contain the subdirectory \code{R}
    (for R code).  Only used if \code{package} is not given.}
  \item{file}{the name of a file containing R code to be checked.  Used
    if neither \code{package} nor \code{dir} are given.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
  \item{verbose}{a logical.  If \code{TRUE}, additional diagnostics are
    printed (and the result is returned invisibly).}
}
\value{
  An object of class \code{"checkFF"}, which currently is a list of the
  (parsed) foreign function calls with no \code{PACKAGE} argument.

  There is a \code{print} method for nicely displaying the information
  contained in such objects.
}
\seealso{
  \code{\link{.C}},
  \code{\link{.Fortran}};
  \code{\link{Foreign}}.
}
\section{Warning}{
  This function is still experimental.  Both name and interface might
  change in future versions.
}
\examples{
checkFF(package = "ts", verbose = TRUE)
}
\keyword{programming}
\keyword{utilities}
\name{checkTnF}
\alias{checkTnF}
\alias{print.checkTnF}
\title{Check R Code for T/F}
\description{
  Checks the specified R code for occurrences of \code{T} or \code{F},
  and gathers the expression containing these.  This is useful as in R
  \code{T} and \code{F} are just variables which are set to the logicals
  \code{TRUE} and \code{FALSE} by default, but are not reserved words
  and hence can be overwritten by the user.  Hence, one should always
  use \code{TRUE} and \code{FALSE} for the logicals.
}
\usage{
checkTnF(package, dir, file, lib.loc = NULL)
}
\arguments{
  \item{package}{a character string naming an installed package.  If
    given, the installed R code of the package is checked.  R code
    installed as an image file cannot be checked.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This should contain the subdirectory \code{R}
    (for R code).  Only used if \code{package} is not given.}
  \item{file}{the name of a file containing R code to be checked.  Used
    if neither \code{package} nor \code{dir} are given.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
}
\value{
  An object of class \code{"checkTnF"} which is a list with the
  expressions found to contain \code{T} or \code{F}.

  There is a \code{print} method for nicely displaying the information
  contained in such objects.
}
\section{Warning}{
  This function is still experimental.  Both name and interface might
  change in future versions.
}
\keyword{utilities}
\keyword{documentation}
\name{checkVignettes}
\alias{checkVignettes}
\alias{print.checkVignettes}
\title{Check Package Vignettes}
\description{
  Check all \code{\link{Sweave}} files of a package by running
  \code{\link{Sweave}} and/or \code{\link{Stangle}} on them. All
  R source code files found after the tangling step are
  \code{\link{source}}ed to check whether all code can be
  executed without errors.
}
\usage{
checkVignettes(package, dir, lib.loc = NULL, tangle = TRUE,
               weave = TRUE, workdir = c("tmp", "src", "cur"),
               keepfiles = FALSE)
}
\arguments{
 \item{package}{a character string naming an installed package.  If
    given, Sweave files are searched in subdirectory \code{doc}.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This subdirectory \code{inst/doc} is searched for
    Sweave files.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
  \item{tangle}{Perform a tangle and \code{\link{source}} the extraced code?}
  \item{weave}{Perform a weave?}
  \item{workdir}{Directory used as working directory while checking the
    vignettes. If \code{"tmp"} then a temporary directory is created,
    this is the default.  If \code{"src"} then the directory containing
    the vignettes itself is used, if \code{"cur"} then the current
    working directory of \R is used.}
  \item{keepfiles}{Delete file in temporary directory? This option is
    ignored when \code{workdir!="tmp"}.}
}
\value{
  An object of class \code{"checkVignettes"} which is a list with the
  error messages found during the tangle and weave steps. There is a
  \code{print} method for nicely displaying the information 
  contained in such objects.
}
\keyword{utilities}
\keyword{documentation}
\name{codoc}
\alias{codoc}
\alias{print.codoc}
\title{Check Code/Documentation Consistency}
\usage{
codoc(package, dir, lib.loc = NULL,
      use.values = FALSE, use.positions = TRUE,
      ignore.generic.functions = FALSE,
      verbose = getOption("verbose"))
}
\description{
  Find inconsistencies between actual and documented usage of \R
  function objects in a package, by comparing names and optionally also
  corresponding positions and default values of the arguments of the
  functions.
}
\arguments{
  \item{package}{a character string naming an installed package.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This must contain the subdirectories \file{man}
    with \R documentation sources (in Rd format) and \file{R} with \R
    code.  Only used if \code{package} is not given.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
  \item{use.positions}{a logical indicating whether to use the positions
    of function arguments when comparing.}
  \item{use.values}{a logical indicating whether to use function default
    values when comparing code and docs.}
  \item{ignore.generic.functions}{if \code{TRUE}, functions the body of
    which contains \code{"UseMethod"} are ignored.}
  \item{verbose}{a logical.  If \code{TRUE}, additional diagnostics are
    printed.}
}
\details{
  The purpose of this function is to check whether the documented usage
  of function objects agrees with their formal arguments as defined in
  the \R code.  This is not always straightforward, in particular as the
  usage information for methods to generic functions often employs the
  name of the generic rather than the method.

  The following algorithm is used.  If an installed package is used, it
  is loaded (unless it is the base package), after possibly detaching an
  already loaded version of the package.  Otherwise, if the sources are
  used, the \R code files of the package are collected and sourced in a
  new environment.  Then, the usage sections of the Rd files are
  extracted and manipulated in order to give function stubs
  corresponding to the indicated usage, which are then sourced in
  another new environment.  For interpreted functions in both the code
  and docs environment, the formals are compared according to the values
  of the arguments \code{use.positions} and \code{use.values}.

  Currently, synopsis sections are used, but multiple usage examples
  (such as in \code{\link{abline}}) are not combined when building the
  stubs.  Occurences of synopsis sections are reported if \code{verbose}
  is true.
}
\value{
  An object of class \code{"codoc"} which is a list the names of which
  are the names of the functions where an inconsistency was found.  The
  elements of the list are lists of length 2 with elements \code{code}
  and \code{docs}, giving the corresponding arguments obtained from the
  function's code and documented usage.

  There is a \code{print} method for nicely displaying the information
  contained in such objects.
}
\seealso{
  \code{\link{undoc}}
}
\keyword{documentation}
\name{tools-internal}
\title{Internal tools functions}
\alias{.listFilesWithExts}
\alias{.loadPackageQuietly}
\alias{.makeS3MethodsStopList}
\alias{.sourceAssignments}
\alias{sQuote}
\alias{SweaveParseOptions}
\alias{SweaveHooks}
\alias{RweaveLatexRuncode}
\alias{RweaveLatexWritedoc}
\alias{RweaveLatexFinish}
\alias{RweaveLatexOptions}
\alias{RweaveChunkPrefix}
\alias{RweaveEvalWithOpt}
\alias{RtangleRuncode}
\alias{RtangleWritedoc}
\alias{RtangleFinish}
\alias{SweaveGetSyntax}
\alias{buildVignettes}
\alias{pkgVignettes}
\description{
  Internal tools functions.
}
\usage{
sQuote(s)
.listFilesWithExts(dir, exts, path = TRUE)
.loadPackageQuietly(package, lib.loc)
.makeS3MethodsStopList(package)
.sourceAssignments(file, envir)
}
\details{
  These are not to be called by the user.
}
\keyword{internal}
\name{undoc}
\alias{undoc}
\alias{print.undoc}
\title{Find Undocumented Objects}
\usage{
undoc(package, dir, lib.loc = NULL)
}
\description{
  Finds the objects in a package which are undocumented, in the sense
  that they are visible to the user (or data objects or S4 classes
  provided by the package), but no documentation entry exists.
}
\arguments{
  \item{package}{a character string naming an installed package.}
  \item{dir}{a character string specifying the path to a package's root
    source directory.  This must contain the subdirectory \file{man}
    with \R documentation sources (in Rd format), and at least one of
    the \file{R} or \file{data} subdirectories with \R code or data
    objects, respectively.}
  \item{lib.loc}{a character vector of directory names of \R libraries,
    or \code{NULL}.  The default value of \code{NULL} corresponds to all
    libraries currently known.  The specified library trees are used to
    to search for \code{package}.}
}
\details{
  This function is useful for package maintainers mostly.  In principle,
  \emph{all} user level \R objects should be documented; note however
  that the precise rules for documenting methods of generic functions
  are still under discussion.
}
\value{
  An object of class \code{"undoc"} which is a list of character vectors
  containing the names of the undocumented objects split according to
  documentation type.  This representation is still experimental, and
  might change in future versions.

  There is a \code{print} method for nicely displaying the information
  contained in such objects.
}
\examples{
undoc("eda")                   # Undocumented objects in 'eda'
}
\keyword{documentation}
