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?
|
|
should \dontrun sections be commented
out?
|
|
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:
-
built on
2024-03-28 at 11:42:11,
-
installed on
2024-03-28 at 11:42:11, and
-
rendered on
2024-04-05 at 21:25:34.
Author(s)
Duncan Murdoch, Brian Ripley
References
https://developer.r-project.org/parseRd.pdf
See Also
parse_Rd, checkRd,
findHTMLlinks, Rd2txt_options,
matchConcordance.
Examples
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()