Rd Converters

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.

Rd2HTML(Rd, out = "", package = "", defines = .Platform$OS.type,
        Links = NULL, Links2 = NULL,
        stages = "render", outputEncoding = "UTF-8",
        dynamic = FALSE, no_links = FALSE, fragment = FALSE,
        stylesheet = "R.css", ...)

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

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

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

a filename or Rd object to use as input.
a filename or connection object to which to write the output.
the package to list in the output.
string(s) to use in #ifdef tests.
at which stage ("build", "install", or "render") should \Sexpr macros be executed? See the notes below.
see the Encodings section below.
logical: set links for render-time resolution by dynamic help system.
logical: suppress hyperlinks to other help topics. Used by R CMD Rdconv.
logical: should fragments of Rd files be accepted? See the notes below.
character: a URL for a stylesheet to be used in the header of the HTML output page.
Links, Links2
NULL or a named (by topics) character vector of links, as returned by findHTMLlinks.
An optional named list of options to pass to Rd2txt_options.
additional parameters to pass to parse_Rd when Rd is a filename.
should \inputencoding lines be written in the file for non-ASCII encodings?
should sections be commented out? commentDonttest{should sections be commented out? }
These functions convert help documents: Rd2HTML produces HTML, Rd2txt produces plain text, Rd2latex produces LaTeX. Rd2ex extracts the examples in the format used by example and Rutilities.

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.

Note that the default for Rd2latex is to output ASCII, including using the second option of \enc markup. This was chosen because use of UTF-8 in LaTeX requires version 2005/12/01 or later, and even with that version the coverage of UTF-8 glyphs is not extensive (and not even as complete as Latin-1).

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 #ifdef unix the current encoding is UTF-8. #endif #ifdef windows the current locale uses a single-byte encoding (except C). (Directional quotes are not attempted in East Asian locales as they are usually double-width, which looks wrong with English text.) #endif

Various aspects of formatting by Rd2txt are controlled by the options argument, documented with the Rd2txt_options function. Changes made using options are temporary, those made with Rd2txt_options are persistent.

When fragment = TRUE, the Rd file will be rendered with no processing of \Sexpr elements or conditional defines using #ifdef or #ifndef. Normally a fragment represents text within a section, but if the first element of the fragment is a section macro, the whole fragment will be rendered as a series of sections, without the usual sorting.

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

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

The \Sexpr macro is a new addition to Rd files. It includes Rcode that will be executed at one of three times: build time (when a package's source code is built into a tarball), 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).

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\Sexpr[stage=install]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}, and
  3. rendered on\Sexpr[stage=render]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}.

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. [object Object],[object Object] https://developer.r-project.org/parseRd.pdf parse_Rd, checkRd, findHTMLlinks, Rd2txt_options. \dontrun{ ## Simulate install and rendering of this page in HTML and text format:

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

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

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

checkRd(Rd) # A stricter test than Rd2HTML uses } documentation

  • Rd2txt
  • Rd2HTML
  • Rd2ex
  • Rd2latex
Documentation reproduced from package tools, version 3.3, License: Part of R @VERSION@

Community examples

Looks like there are no examples yet.