| % File src/library/tools/man/Rd2HTML.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2008-2022 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{Rd2HTML} |
| \alias{Rd2txt} |
| \alias{Rd2HTML} |
| \alias{Rd2ex} |
| \alias{Rd2latex} |
| \title{ Rd Converters } |
| \description{ |
| These functions take the output of \code{\link{parse_Rd}()}, an |
| \code{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"), |
| ...) |
| |
| 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) |
| |
| Rd2ex(Rd, out = "", defines = .Platform$OS.type, |
| stages = "render", outputEncoding = "UTF-8", |
| commentDontrun = TRUE, commentDonttest = FALSE, ...) |
| } |
| \arguments{ |
| \item{Rd}{ a filename or \code{Rd} object to use as input. } |
| \item{out}{a filename or connection object to which to write the |
| output. The default \code{out = ""} is equivalent to |
| \code{out = \link{stdout}()}.} |
| \item{package}{ the package to list in the output. } |
| \item{defines}{ string(s) to use in \verb{#ifdef} tests. } |
| \item{stages}{ at which stage (\code{"build"}, \code{"install"}, or |
| \code{"render"}) should \verb{\Sexpr} macros be executed? See the |
| notes below.} |
| \item{outputEncoding}{ see the \sQuote{Encodings} section below.} |
| \item{dynamic}{logical: set links for render-time resolution by |
| dynamic help system.} |
| \item{no_links}{logical: suppress hyperlinks to other help topics. |
| Used by \command{R CMD \link{Rdconv}}.} |
| \item{fragment}{logical: should fragments of Rd files be accepted? See the |
| notes below.} |
| \item{stylesheet}{character: a URL for a stylesheet to be used in the header |
| of the HTML output page.} |
| \item{texmath}{character: controls how mathematics in \verb{\eqn} and |
| \verb{\deqn} commands are typeset in HTML output. Useful values |
| are \code{"katex"} (default) and \code{"mathjax"} to use |
| \href{https://katex.org/}{KaTeX} or |
| \href{https://www.mathjax.org/}{MathJax} respectively, otherwise |
| basic substitutions are used. May be ignored under certain |
| circumstances, e.g., if the help page already uses macros from the |
| \code{\link[mathjaxr]{mathjaxr}} package. |
| } |
| \item{Links, Links2}{\code{NULL} or a named (by topics) character vector of |
| links, as returned by \code{\link{findHTMLlinks}}.} |
| \item{options}{An optional named list of options to pass to |
| \code{\link{Rd2txt_options}}.} |
| \item{...}{ additional parameters to pass to \code{\link{parse_Rd}} when |
| \code{Rd} is a filename. } |
| \item{writeEncoding}{should \verb{\inputencoding} lines be written in |
| the file for non-ASCII encodings?} |
| \item{commentDontrun}{should \verb{\dontrun} sections be commented |
| out?} |
| \item{commentDonttest}{should \verb{\donttest} sections be commented out?} |
| } |
| \details{ |
| These functions convert help documents: \code{Rd2HTML} produces HTML, |
| \code{Rd2txt} produces plain text, \code{Rd2latex} produces LaTeX. |
| \code{Rd2ex} extracts the examples in the format used by |
| \code{\link{example}} and \R utilities. |
| |
| Each of the functions accepts a filename for an Rd file, and |
| will use \code{\link{parse_Rd}} to parse it before applying the |
| conversions or checks. |
| |
| The difference between arguments \code{Link} and \code{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 \code{Rd2latex} was \code{outputEncoding = "ASCII"}, |
| including using the second option of \verb{\enc} markup, because \LaTeX |
| versions did not provide enough coverage of UTF-8 glyphs for a long time. |
| |
| \code{Rd2txt} will format text paragraphs to a width determined by |
| \code{width}, with appropriate margins. The default is to be close to |
| the rendering in versions of \R < 2.10.0. |
| |
| \code{Rd2txt} will use directional quotes (see \code{\link{sQuote}}) |
| if option \code{"useFancyQuotes"} is true (usually the default, |
| see \code{\link{sQuote}}) and |
| #ifdef unix |
| the current encoding is UTF-8. |
| #endif |
| #ifdef windows |
| the current encoding is UTF-8 or 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 \code{Rd2txt} are controlled by the |
| \code{options} argument, documented with the \code{\link{Rd2txt_options}} |
| function. Changes made using \code{options} are temporary, those |
| made with \code{\link{Rd2txt_options}} are persistent. |
| |
| When \code{fragment = TRUE}, the \code{Rd} file will be rendered |
| with no processing of \verb{\Sexpr} elements or conditional defines |
| using \verb{#ifdef} or \verb{#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. |
| } |
| \section{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 \samp{encoding} section for there to be any hope of correct |
| rendering. |
| |
| For output, the \code{outputEncoding} argument will be used: |
| \code{outputEncoding = ""} will choose the native encoding for the |
| current system. |
| |
| If the text cannot be converted to the \code{outputEncoding}, byte |
| substitution will be used (see \code{\link{iconv}}): \code{Rd2latex} |
| and \code{Rd2ex} give a warning. |
| } |
| |
| \note{ |
| The \verb{\Sexpr} macro is a new addition to Rd files. It includes |
| \R code that will be executed at one of three times: \emph{build} time |
| (when a package's source code is built into a tarball), |
| \emph{install} time (when the package is installed or |
| built into a binary package), and \emph{render} time (when the man |
| page is converted to a readable format). |
| |
| For example, this man page was: |
| \enumerate{ |
| \item built on |
| \Sexpr[stage=build]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}, |
| \item installed on |
| \Sexpr[stage=install]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}, and |
| \item rendered on |
| \Sexpr[stage=render]{format(Sys.time(), "\%Y-\%m-\%d at \%H:\%M:\%S")}. |
| } |
| } |
| |
| \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 \code{Rd2latex}, the output name is given an |
| attribute \code{"latexEncoding"} giving the encoding of the file in a |
| form suitable for use with the LaTeX \samp{inputenc} package. |
| } |
| \author{ |
| Duncan Murdoch, Brian Ripley |
| } |
| \references{ \url{https://developer.r-project.org/parseRd.pdf} } |
| \seealso{ |
| \code{\link{parse_Rd}}, \code{\link{checkRd}}, |
| \code{\link{findHTMLlinks}}, \code{\link{Rd2txt_options}}. |
| } |
| \examples{\donttest{ |
| |
| \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 |
| }}} |
| \keyword{ documentation } |