Rd2HTML {tools}R Documentation

Rd Converters

Description

These functions take the output of parse_Rd(), an Rd object, 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 = if (dynamic) "/doc/html/R.css" else "R.css",
        texmath = getOption("help.htmlmath"),
        concordance = FALSE,
        standalone = TRUE,
        hooks = list(),
        toc = isTRUE(getOption("help.htmltoc")),
        Rhtml = FALSE,
        ...)

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

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

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. The default out = "" is equivalent to out = stdout().

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.

texmath

character: controls how mathematics in ⁠\eqn⁠ and ⁠\deqn⁠ commands are typeset in HTML output. Useful values are "katex" (default) and "mathjax" to use KaTeX or MathJax respectively, otherwise basic substitutions are used. May be ignored under certain circumstances, e.g., if the help page already uses macros from the mathjaxr package.

concordance

Whether concordance data should be embedded in the output file and attached to the return value.

standalone

logical: whether the output is intended to be a standalone HTML file. If FALSE, the header and footer are omitted, so that the output can be combined with other fragments.

hooks

A list of functions controlling details of output. Currently the only component used is pkg_href, which is used by pkg2HTML to determine the output HTML file path given a package name as input.

toc

logical: whether the HTML output should include a table of contents. Ignored unless standalone = TRUE.

Rhtml

logical: whether the output is intended to be a Rhtml file that can be processed using knitr. If TRUE, the examples section is wrapped inside a rcode block.

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.

Before R 3.6.0, the default for Rd2latex was outputEncoding = "ASCII", including using the second option of ⁠\enc⁠ markup, because LaTeX versions did not provide enough coverage of UTF-8 glyphs for a long time.

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 (usually the default, see sQuote) and the current encoding is UTF-8.

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. For Rd2HTML with standalone = FALSE, an attribute "info" gives supplementary information such as the contents of the name and title fields. This is currently experimental, and the details are subject to change.

For Rd2HTML and Rd2latex with concordance = TRUE, a "concordance" attribute is added, containing an Rconcordance object.

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 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 2024-03-22 at 01:47:59,

  2. installed on 2024-03-22 at 01:47:59, and

  3. rendered on 2024-03-22 at 01:48:05.

Author(s)

Duncan Murdoch, Brian Ripley

References

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

See Also

parse_Rd, checkRd, findHTMLlinks, Rd2txt_options, matchConcordance.

Examples


## Simulate rendering of this (installed) page in HTML and text format
Rd <- Rd_db("tools")[["Rd2HTML.Rd"]]

outfile <- tempfile(fileext = ".html")
Rd2HTML(Rd, outfile, package = "tools") |> browseURL()

outfile <- tempfile(fileext = ".txt")
Rd2txt(Rd, outfile, package = "tools") |> file.show()

[Package tools version 4.4.0 Index]