R: Rd Converters

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, 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, ...)

### 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`.
`fragment` | logical: should fragments of Rd files be accepted? See the notes below.
`stylesheet` | 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`.
`options` | An optional named list of options to pass to `Rd2txt_options`.
`...` | additional parameters to pass to `parse_Rd` when `Rd` is a filename.
`writeEncoding` | should `\inputencoding` lines be written in the file for non-ASCII encodings?
`commentDontrun` | should `\dontrun` sections be commented out?
`commentDonttest` | should `\donttest` sections be commented out?

### Details

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 R utilities.

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

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.

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

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), 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 2019-07-02 at 00:40:30,

2. installed on 2019-07-02 at 00:40:30, and

3. rendered on 2019-07-02 at 00:40:50.

### Author(s)

Duncan Murdoch, Brian Ripley

### References

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

### See Also

`parse_Rd`, `checkRd`, `findHTMLlinks`, `Rd2txt_options`.

### Examples

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

    ## End(Not run)

[Package tools version 3.5.1 Index]