The R Project SVN R

% File src/library/tools/man/Rd2HTML.Rd
% Part of the R package, http://www.R-project.org
% Copyright 2008-9 R Core Development Team
% Distributed under GPL 2 or later

\name{Rd2HTML}
\alias{Rd2txt}
\alias{Rd2HTML}
\alias{Rd2ex}
\alias{Rd2latex}
\alias{checkRd}
\alias{findHTMLlinks}
\title{ Work with an Rd object }
\description{
  These functions take the output of the
  \code{\link{parse_Rd}} function and check it or produce a help
  page from it.  As they are mainly intended for internal
  use, their interfaces are subject to
  change.
}
\usage{
Rd2HTML(Rd, out = "", package = "", defines = .Platform$OS.type,
        Links = NULL, CHM = FALSE,
        stages = "render", outputEncoding = "UTF-8", ...)

Rd2txt(Rd, out = "", package = "", defines = .Platform$OS.type,
       stages = "render", outputEncoding = "", ...)

Rd2latex(Rd, out = "", defines = .Platform$OS.type,
         stages = "render", outputEncoding = "latin1", ...)

Rd2ex(Rd, out = "", defines = .Platform$OS.type,
      stages = "render", outputEncoding = "UTF-8", ...)

checkRd(Rd, defines = .Platform$OS.type, stages = "render",
        unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE)

findHTMLlinks(pkgDir = "", lib.loc = NULL)
}
\arguments{
  \item{Rd}{ a filename or \code{Rd} object to use as input. }
  \item{out}{ a filename or connection object to which to write the output. }
  \item{package}{ the package to list in the output. }
  \item{defines}{ string(s) to use in \code{"#ifdef"} tests. }
  \item{stages}{ at which stage (\code{"build"}, \code{"install"}, or
    \code{"render"} should \\Sexpr macros be executed? See the notes below.}
  \item{outputEncoding}{ see the \sQuote{Encodings} section below.}
  \item{Links}{\code{NULL} or a named (by topics) character vector of
    links, as returned by \code{findHTMLlinks}.}
  \item{CHM}{logical: prepare HTML suitable for Compiled HTML?}
  \item{unknownOK}{ unrecognized macros are treated as errors if
    \code{FALSE}, otherwise warnings. }
  \item{listOK}{ unnecessary non-empty braces (e.g. around text, not
    as an argument) are treated as errors if \code{FALSE}, otherwise warnings. }
  \item{...}{ additional parameters to pass to \code{\link{parse_Rd}} when
    \code{Rd} is a filename. }
  \item{def_enc}{logical: has the package declared an encoding, so tests
    for non-ASCII text are suppressed?}
  \item{pkgDir}{the top-level directory of an installed package.}
  \item{lib.loc}{character vector describing the location of \R library trees
    to scan: the default indicates \code{\link{.libPaths}()}.}
}
\details{

  The \code{Rd2*} functions convert man pages:
  \code{Rd2HTML} produces HTML (or compiled HTML, for Windows),
  \code{Rd2txt} produces plain text, \code{Rd2latex} produces
  LaTeX input.  By default, \code{outputEncoding} is set to \code{""}
  and the native character encoding (shown by \code{\link{localeToCharset}})
  is used.

  The converters are still in development, and may still make some errors
  in rendering.

  \code{Rd2ex} extracts the examples in the format used by
  \code{\link{example}} and \R utilities.  it reproduces the previous
  version up to
  \itemize{
    \item The parser does not interpret markup in \R comments: this used
    to be done.
    \item Small improvements in layout.
  }

  \code{checkRd} makes consistency checks on an Rd file, confirming that
  required sections are present, etc.

  Each of the above functions accepts a filename for an Rd file, and
  will use \code{\link{parse_Rd}} to parse it before applying the
  conversions or checks.

  \code{findHTMLlinks} tries to resolve links from one man page to another.  It
  uses in decreasing priority
  \itemize{
    \item The package in \code{pkgDir}: this is used when converting
    HTML help for that package.
    \item The packages that are loaded in a vanilla \R session.
    \item Other packages found in the library trees specified by
    \code{lib.loc} in the order of the trees and alphabetically within a
    library tree.
  }
}
\section{Encodings}{
  Rd files are normally intended to be rendered on a wide variety of
  systems, so care must be taken in the encoding of non-ASCII
  characters.  In general, any such encoding should be declared using
  the \samp{encoding} section for there to be any hope of correct
  rendering.  Avoid exotic encodings unless absolutely necessary: all
  input will be translated to UTF-8, and the quality of such
  translations is poor on some older systems.

  For output, the \code{outputEncoding} variable will be used:
  \code{outputEncoding=""} will choose the native encoding for the
  current system.  The \code{Rd2latex} function is an exception to this
  rule, because LaTeX installations vary considerably in their ability
  to handle encodings.  If an input file contains an \samp{encoding}
  section, \code{Rd2latex} will use that as the output encoding as well.
  Unfortunately, on some older LaTeX installations the conversion to
  UTF-8 and back is not perfect, and some characters may not be rendered
  properly.
}

\note{
  The \samp{\\Sexpr} macro is a new addition to Rd files.  It includes
  \R code that will be executed at one of three times: \emph{build} time
  (when a package's source code is built into a tarball, not yet
  implemented), \emph{install} time (when the package is installed or
  built into a binary package), and \emph{render} time (when the man
  page is converted to a readable format).

  Currently only text format man pages render when displayed; all other
  formats render when installed.

  For example, this man page was:
  \enumerate{
    \item built on
    \Sexpr[stage=build]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")},
    \item installed on
    \Sexpr[stage=install]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}, and
    \item rendered on
    \Sexpr[stage=render]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}.
  }
  Because build-time execution is not yet supported, the first of these
  will display as a macro; the other two may or may not, depending on the
  build of \R.  (Note that escapes, e.g. for \samp{\%}, may not be
  identical in this display, but the displayed Rd code should parse to the
  same object.)
}

\value{
  The \code{Rd2*} functions are executed mainly for the side effect of
  writing the converted help page.  Their value is the name of the output
  file (invisibly).  For \code{Rd2latex}, the output name is given an
  attribute \code{"latexEncoding"} giving the encoding of the file in a
  form suitable for use with the LaTeX \samp{inputenc} package.

  \code{checkRd} returns \code{TRUE} if the file has no errors; it
  generates an R error otherwise.

  \code{findHTMLlinks} returns a named character vector of relative
  file paths, in the same package or in a package in the same library tree.
}
\author{
  Duncan Murdoch, Brian Ripley
}
\references{ \url{http://developer.r-project.org/parseRd.pdf} }
\seealso{
  \code{\link{parse_Rd}}
}
\examples{\donttest{

\dontrun{
## Simulate an install and rendering of this page in HTML and text format:

Rd <- file.path("src/library/tools/Rd2HTML.Rd")

outfile <- paste(tempfile(), ".html", sep="")
browseURL(Rd2HTML(Rd, outfile, package="tools", stages=c("install", "render")))

outfile <- paste(tempfile(), ".txt", sep="")
file.show(Rd2txt(Rd, outfile, package="tools", stages=c("install", "render")))

checkRd(con) # A stricter test than Rd2HTML uses
}}}
\keyword{ documentation }