Rd2HTML {tools} | R Documentation |
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, ...) 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", ..., writeEncoding = TRUE) Rd2ex(Rd, out = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "UTF-8", ...)
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 #ifdeftests. |
stages |
at which stage ("build" , "install" , or
"render" ) should \Sexprmacros 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. |
writeEncoding |
should \inputencodinglines be written in the file for non-ASCII encodings? |
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
\encmarkup. 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 encoding is UTF-8.
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.
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
\Sexprmacro 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:
Duncan Murdoch, Brian Ripley
http://developer.r-project.org/parseRd.pdf
parse_Rd
, checkRd
,
findHTMLlinks
.
## 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)