Rd2HTML {tools}R Documentation

Rd Converters

Description

These functions take the output of the parse_Rd function and 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, Links2 = NULL,
        stages = "render", outputEncoding = "UTF-8", 
        dynamic = FALSE, no_links = FALSE, ...)

Rd2txt(Rd, out = "", package = "", defines = .Platform$OS.type,
       stages = "render", outputEncoding = "",
       width = getOption("help_text_width", 80L), ...)

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

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

Arguments

Rd a filename or Rd object to use as input.
out a filename or connection object to which to write the output.
package the package to list in the output.
defines string(s) to use in
#ifdef
tests.
stages at which stage ("build", "install", or "render") should
\Sexpr
macros be executed? See the notes below.
outputEncoding see the ‘Encodings’ section below.
dynamic logical: set links for render-time resolution by dynamic help system.
no_links logical: suppress hyperlinks to other help topics. Used by R CMD Rdconv.
Links, Links2 NULL or a named (by topics) character vector of links, as returned by findHTMLlinks.
width The intended page width (in characters) for which the text rendering should be designed.
... additional parameters to pass to parse_Rd when Rd is a filename.

Details

These functions convert help pages: Rd2HTML produces HTML (or compiled HTML, for Windows), Rd2txt produces plain text, Rd2latex produces LaTeX input. By default, outputEncoding is set to "" and the native character encoding (shown by localeToCharset) is used.

Rd2ex extracts the examples in the format used by example and R utilities. it reproduces the previous version up to

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

The difference between arguments Link and Link2 is that links are looked in them in turn, so lazy-evaluation can be used to only do a second-level search for links if required.

Rd2txt will format text paragraphs to a width determined by width, with appropriate margins. The default is to be close to the rendering in versions of R < 2.10.0.

Rd2txt will use directional quotes (see sQuote) if option "useFancyQuotes" is true (the default) and the current encoding is UTF-8.

Value

These 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 Rd2latex, the output name is given an attribute "latexEncoding" giving the encoding of the file in a form suitable for use with the LaTeX inputenc package.

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 encoding section for there to be any hope of correct rendering.

For output, the outputEncoding argument will be used: outputEncoding = "" will choose the native encoding for the current system. The Rd2latex function is an exception to this rule, because UTF-8 is not a viable universal choice for LaTeX: if an input file contains an encoding section, Rd2latex will use that for the output encoding.

If the text cannot be converted to the outputEncoding, byte substitution will be used (see iconv): Rd2latex and Rd2ex give a warning.

Note

The

\Sexpr
macro is a new addition to Rd files. It includes R code that will be executed at one of three times: build time (when a package's source code is built into a tarball, not yet implemented), install time (when the package is installed or built into a binary package), and 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:

  1. built on \Sexpr[stage=build]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")},
  2. installed on 2009-12-23 at 00:11:05, and
  3. rendered on 2009-12-23 at 00:11:33.
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 %, may not be identical in this display, but the displayed Rd code should parse to the same object.)

Author(s)

Duncan Murdoch, Brian Ripley

References

http://developer.r-project.org/parseRd.pdf

See Also

parse_Rd, checkRd, findHTMLlinks.

Examples


## Not run: 
## Simulate 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

## End(Not run)

[Package tools version 2.10.1 Index]