| % File src/library/tools/man/parse_Rd.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2008-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{parse_Rd} |
| \alias{parse_Rd} |
| \alias{print.Rd} |
| \alias{as.character.Rd} |
| \title{Parse an Rd File} |
| \description{ |
| This function reads an R documentation (Rd) file and parses it, for |
| processing by other functions. |
| } |
| \usage{ |
| parse_Rd(file, srcfile = NULL, encoding = "unknown", |
| verbose = FALSE, fragment = FALSE, warningCalls = TRUE, |
| macros = file.path(R.home("share"), "Rd", "macros", "system.Rd"), |
| permissive = FALSE) |
| \method{print}{Rd}(x, deparse = FALSE, \dots) |
| \method{as.character}{Rd}(x, deparse = FALSE, \dots) |
| } |
| \arguments{ |
| \item{file}{A filename or text-mode connection. At present filenames |
| work best.} |
| \item{srcfile}{\code{NULL}, or a \code{"srcfile"} object. See the |
| \sQuote{Details} section.} |
| \item{encoding}{Encoding to be assumed for input strings.} |
| \item{verbose}{Logical indicating whether detailed parsing |
| information should be printed.} |
| \item{fragment}{Logical indicating whether file represents a complete |
| Rd file, or a fragment.} |
| \item{warningCalls}{Logical: should parser warnings include the call?} |
| \item{macros}{Filename or environment from which to load additional |
| macros, or a logical value. See the Details below.} |
| \item{permissive}{Logical indicating that unrecognized macros |
| should be treated as text with no warning.} |
| \item{x}{An object of class Rd.} |
| \item{deparse}{If \code{TRUE}, attempt to reinstate the escape characters |
| so that the resulting characters will parse to the same object.} |
| \item{\dots}{Further arguments to be passed to or from other methods.} |
| } |
| \details{ |
| This function parses \file{Rd} files according to the specification given |
| in \url{https://developer.r-project.org/parseRd.pdf}. |
| |
| It generates a warning for each parse error and attempts to continue |
| parsing. In order to continue, it is generally necessary to drop some |
| parts of the file, so such warnings should not be ignored. |
| |
| Files without a marked encoding are by default assumed to be in the |
| native encoding. An alternate default can be set using the |
| \code{encoding} argument. All text in files is translated to the |
| UTF-8 encoding in the parsed object. |
| |
| As from \R version 3.2.0, User-defined macros may be given in a |
| separate file using \samp{\newcommand} or \samp{\renewcommand}. |
| An environment may also be given: it would be produced by |
| \code{\link{loadRdMacros}}, \code{\link{loadPkgRdMacros}}, or |
| by a previous call to \code{parse_Rd}. If a logical value |
| is given, only the default built-in macros will be used; |
| \code{FALSE} indicates that no \code{"macros"} attribute |
| will be returned with the result. |
| |
| The \code{permissive} argument allows text to be parsed that is |
| not completely in Rd format. Typically it would be LaTeX code, |
| used in an Rd fragment, e.g.\sspace{}in a \code{\link{bibentry}}. |
| With \code{permissive = TRUE}, this will be passed through as plain |
| text. Since \code{parse_Rd} doesn't know how many arguments |
| belong in LaTeX macros, it will guess based on the presence |
| of braces after the macro; this is not infallible. |
| } |
| \value{ |
| \code{parse_Rd} returns an object of class \code{"Rd"}. The |
| internal format of this object is subject to change. The |
| \code{as.character()} and \code{print()} methods defined for the |
| class return character vectors and print them, respectively. |
| |
| Unless \code{macros = FALSE}, the object will have an attribute |
| named \code{"macros"}, which is an environment containing the |
| macros defined in \code{file}, in a format that can be used for |
| further \code{parse_Rd} calls in the same session. It is not |
| guaranteed to work if saved to a file and reloaded in a different |
| session. |
| } |
| \references{ \url{https://developer.r-project.org/parseRd.pdf} } |
| \author{ Duncan Murdoch } |
| \seealso{ |
| \code{\link{Rd2HTML}} for the converters that use the output of |
| \code{parse_Rd()}. |
| } |
| \keyword{utilities} |
| \keyword{documentation} |