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

\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 by \dQuote{running them}, i.e., \code{\link{parse}()} and
  \code{\link{eval}()} each.
}
\usage{
RweaveLatex()

RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
                 debug = FALSE, stylepath, \dots)
}
\arguments{
  \item{file}{Name of Sweave source file.  See the description of the
    corresponding argument of \code{\link{Sweave}}.}
  \item{syntax}{An object of class \code{SweaveSyntax}.}
  \item{output}{Name of output file.  The default is to remove extension
    \file{.nw}, \file{.Rnw} or \file{.Snw} and to add
    extension \file{.tex}.  Any directory paths 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}{See \sQuote{Details}.}
  \item{\dots}{named values for the options listed in \sQuote{Supported
      Options}.}
}
\details{
  The \LaTeX file generated needs to contain the line
  \samp{\\usepackage\{Sweave\}}, and if this is not present in the
  Sweave source file (possibly in a comment), it is inserted by the
  \code{RweaveLatex} driver as last line before the \samp{\\begin{document}}
  statement. If \code{stylepath = TRUE}, a hard-coded
  path to the file \file{Sweave.sty} in the \R installation is set in
  place of \code{Sweave}.  The hard-coded path makes the \LaTeX file less
  portable, but avoids the problem of installing the current version of
  \file{Sweave.sty} to some place in your TeX input path.  However, TeX
  may not be able to process the hard-coded path if it contains spaces
  (as it often will under Windows) or TeX special characters.

  The default for \code{stylepath} is now taken from the environment
  variable \env{SWEAVE_STYLEPATH_DEFAULT}, or is \code{FALSE} it that is
  unset or empty.  If set, it should be exactly \code{TRUE} or
  \code{FALSE}: any other values are taken as \code{FALSE}.

  The simplest way for frequent Sweave users to ensure that
  \file{Sweave.sty} is in the TeX input path is to add
  \file{\var{R_HOME}/share/texmf} as a \sQuote{texmf tree} (\sQuote{root
  directory} in the parlance of the \sQuote{MiKTeX settings} utility).

  By default, \file{Sweave.sty} loads the \samp{graphicx} \LaTeX package
  and sets the width of all included graphics to:\cr
  \samp{\\setkeys{Gin}{width=0.8\\textwidth}}.

  This setting (defined in the \samp{graphicx} package)
  affects the width size option passed to the
  \samp{\\includegraphics{}} directive for each plot file and in turn
  impacts the scaling of your plot files as they will appear in your
  final document.

  Thus, for example, you may set \code{width=3} in your figure chunk and
  the generated graphics files will be set to 3 inches in
  width.  However, the width of your graphic in your final document will
  be set to \samp{0.8\\textwidth} and the height dimension will be
  scaled accordingly.  Fonts and symbols will be similarly scaled in the
  final document.

  You can adjust the default value by including the
  \samp{\\setkeys{Gin}{width=...}} directive in your \file{.Rnw} file
  after the \samp{\\begin{document}} directive and changing the
  \code{width} option value as you prefer, using standard \LaTeX
  measurement values.

  If you wish to override this default behavior entirely, you can add a
  \samp{\\usepackage[nogin]{Sweave}} directive in your preamble.  In this
  case, no size/scaling options will be passed to the
  \samp{\\includegraphics{}} directive and the \code{height} and
  \code{width} options will determine both the runtime generated graphic
  file sizes and the size of the graphics in your final document.

  \file{Sweave.sty} also supports the \samp{[nofontenc]} option, which
  skips the default inclusion of \samp{\\usepackage[T1]{fontenc}}
  for pdfTeX processing.

  It also supports the \samp{[inconsolata]} option, to render monospaced
  text in \code{inconsolata}, the font used by default for \R help
  pages.

  The use of fancy quotes (see \code{\link{sQuote}}) can cause problems
  when setting \R output in non-UTF-8 locales (note that pdfTeX assumes
  UTF-8 by default since 2018).  Either set
  \code{\link{options}(useFancyQuotes = FALSE)} or arrange that \LaTeX is
  aware of the encoding used (in \R < 4.2.0, Windows users needed a
  \samp{\\usepackage[cp1252]\{inputenc\}} declaration or similar,
  see \code{\link{l10n_info}()}) and
  ensure that typewriter fonts containing directional quotes are used.

  Some \LaTeX graphics drivers do not include \samp{.png} or \samp{.jpg}
  in the list of known extensions.  To enable them, add something like
  \samp{\\DeclareGraphicsExtensions{.png,.pdf,.jpg}} to the preamble of
  your document or check the behavior of your graphics driver.  When
  both \code{pdf} and \code{png} are \code{TRUE} both files will be
  produced by \code{Sweave}, and their order in the
  \samp{DeclareGraphicsExtensions} list determines which will be used by
  \command{pdflatex}.
}

\section{Supported Options}{
  \code{RweaveLatex} supports the following options for code chunks (the
  values in parentheses show the default values).  Character string
  values should be quoted when passed from \code{\link{Sweave}} through
  \code{\dots} but not when used in the header of a code chunk.
  \describe{
    \item{engine:}{character string (\code{"R"}).  Only chunks with
      \code{engine} equal to \code{"R"} or \code{"S"} are processed.}

    \item{echo:}{logical (\code{TRUE}). Include \R code in the output
      file?}

    \item{keep.source:}{logical (\code{TRUE}).  When echoing, if
      \code{TRUE} the original source is copied to the file.  Otherwise,
      deparsed source is echoed.} 

    \item{eval:}{logical (\code{TRUE}).  If \code{FALSE}, the code chunk
      is not evaluated, and hence no text nor graphical output
      produced.}

    \item{results:}{character string (\code{"verbatim"}).  If
      \code{"verbatim"}, the output of \R commands is included in the
      verbatim-like \samp{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).  Values can be abbreviated.}

    \item{print:}{logical (\code{FALSE}).  If \code{TRUE}, this forces
      auto-printing of all expressions.}

    \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 similar statements.}

    \item{split:}{logical (\code{FALSE}).  If \code{TRUE}, text output
      is written to separate files for each code chunk.}

    \item{strip.white:}{character string (\code{"true"}).  If
      \code{"true"}, blank lines at the beginning and end of output are
      removed.  If \code{"all"}, then all blank lines are removed from
      the output.  If \code{"false"} then blank lines are retained.

      A \sQuote{blank line} is one that is empty or includes only
      whitespace (spaces and tabs).

      Note that blank lines in a code chunk will usually produce a
      prompt string rather than a blank line on output.
    }

    \item{prefix:}{logical (\code{TRUE}).  If \code{TRUE} generated
      filenames of figures and output all have the common prefix given
      by the \code{prefix.string} option: otherwise only unlabelled
      chunks use the prefix.}

    \item{prefix.string:}{a character string, default is the name of the
      source file (without extension).  Note that this is used as part
      of filenames, so needs to be portable.}

    \item{include:}{logical (\code{TRUE}), indicating whether input
      statements for text output (if \code{split = TRUE}) and
      \samp{\\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.  The labels for figure
      chunks are used as part of the file names, so should preferably be
      alphanumeric.}

    \item{eps:}{logical (\code{FALSE}), indicating whether EPS figures
      should be generated.  Ignored if \code{fig = FALSE}.}

    \item{pdf:}{logical (\code{TRUE}), indicating whether PDF figures
      should be generated.  Ignored if \code{fig = FALSE}.}

    \item{pdf.version, pdf.encoding, pdf.compress:}{passed to
      \code{\link{pdf}} to set the version, encoding and compression (or
      not).  Defaults taken from \code{pdf.options()}.}

    \item{png:}{logical (\code{FALSE}), indicating whether PNG figures
      should be generated.  Ignored if \code{fig = FALSE}.
      Only available in \eqn{\R \ge 2.13.0}{R >= 2.13.0}.}

    \item{jpeg:}{logical (\code{FALSE}), indicating whether JPEG figures
      should be generated.  Ignored if \code{fig = FALSE}.
      Only available in \eqn{\R \ge 2.13.0}{R >= 2.13.0}.}

    \item{grdevice:}{character (\code{NULL}): see section
      \sQuote{Custom Graphics Devices}.  Ignored if \code{fig = FALSE}.
      Only available in \eqn{\R \ge 2.13.0}{R >= 2.13.0}.}

    \item{width:}{numeric (6), width of figures in inches.  See
      \sQuote{Details}.}

    \item{height:}{numeric (6), height of figures in inches.  See
      \sQuote{Details}.}

    \item{resolution:}{numeric (300), resolution in pixels per inch:
      used for PNG and JPEG graphics.  Note that the default is a fairly
      high value, appropriate for high-quality plots.  Something like
      \code{100} is a better choice for package vignettes.}

    \item{concordance:}{logical (\code{FALSE}).  Write a concordance
      file to link the input line numbers to the output line numbers.
      This is an experimental feature; see the source code for the
      output format, which is subject to change in future releases.}

    \item{figs.only:}{logical (\code{FALSE}).
      By default each figure chunk is run once, then re-run for each
      selected type of graphics.  That will open a default graphics
      device for the first figure chunk and use that device for the first
      evaluation of all subsequent chunks.  If this option is true, the
      figure chunk is run only for each selected type of graphics, for
      which a new graphics device is opened and then closed.}
  }

  In addition, users can specify further options, either in the header
  of an individual code section or in a \samp{\\SweaveOpts\{\}} line in
  the document. For unknown options, their type is set at first use.
}

\section{Custom Graphics Devices}{
  If option \code{grdevice} is supplied for a code chunk with both
  \code{fig} and \code{eval} true, the following call is made
  \preformatted{  get(options$grdevice, envir = .GlobalEnv)(name=, width=,
                                            height=, options)
}
  which should open a graphics device.  The chunk's code is then
  evaluated and \code{\link{dev.off}} is called.  Normally a function of
  the name given will have been defined earlier in the Sweave document, e.g.
\preformatted{<<results=hide>>=
my.Swd <- function(name, width, height, ...)
  grDevices::png(filename = paste(name, "png", sep = "."),
                 width = width, height = height, res = 100,
                 units = "in", type = "quartz", bg = "transparent")
@
}
  Alternatively for \R >= 3.4.0, if the function exists in a package
  (rather than the \code{.GlobalEnv}) it can be used by setting
  \code{grdevice = "pkg::my.Swd"} (or with \samp{:::} instead of
  \samp{::} if the function is not exported).

  Currently only one custom device can be used for each chunk, but
  different devices can be used for different chunks.

  A replacement for \code{\link{dev.off}} can be provided as a function
  with suffix \code{.off}, e.g.\sspace{}\code{my.Swd.off()} or
  \code{pkg::my.Swd.off()}, respectively.
}

\section{Hook Functions}{
  Before each code chunk is evaluated, zero or more hook functions can
  be executed.  If \code{getOption("SweaveHooks")} is set, it is taken
  to be a named list of hook functions.  For each \emph{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 logical options and
  associate arbitrary hooks with them.  E.g., one could define a hook
  function for a new option called \code{clean} that removes all objects
  in the workspace.  Then all code chunks specified with
  \code{clean = TRUE} would start operating on an empty workspace.
}

\author{Friedrich Leisch and R-core}

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

  \code{\link{Sweave}}, \code{\link{Rtangle}}
}

\keyword{utilities}