Rd_fun: Return all or selected sections of a help topic as an Rd...
In gbRd: Utilities for processing Rd objects and files

Description Usage Arguments Details Value Note Author(s) Examples

Return all or selected sections of a help topic as an Rd object. The help topic may be an Rd object, a character string (for the help function), or the value returned by the help function.

1 2	Rd_fun(x, topic, pkgname = "", help_type = "text", verbose = FALSE, try.all.packages = FALSE, keep_section = TRUE)

`x`	the help object. Its class may be "Rd", "character", or "help_files_with_topic".
`topic`	unused, see Details
`pkgname`	unused, see Details
`help_type`	type of help, see Details and `help`.
`verbose`	logical value, see `help`.
`try.all.packages`	logical value, see `help`.
`keep_section`	the section(s) to keep. If it is a character vector of length at least one, the sections listed in it (plus `\title` and `\name`) are kept in the result, the rest are dropped. Otherwise all sections are returned.

If the class of x is neither "Rd" nor "help_files_with_topic", x is assumed to be appropriate for a call to help. The call is made to obtain an object of class "help_files_with_topic", which is then processed as below. Arguments help_type, verbose and try.all.packages are used only in this case.

If the class of x is "help_files_with_topic" (usually the result of a call to help), then an Rd object is obtained using tools:::fetchRdDB.

The Rd object (x itself or the one obtained as described above) is examined and sections are retained or dropped as specified by argument keep_section. Sections \title and \name are always kept in the returned value since otherwise the Rd object is considered invalid by (some of?) the system functions.

an Rd object

Note that help works with ‘installed’ help. So, when the Rd object is obtained via a call to help it will not necessarilly be the one that would be obtained from the original Rd file if that contains \Sexpr instructions with stage=build or stage=install optional argument. This is not a problem for the intended purpose of this package to allow for extraction of pieces of the help for selective display and related run-time actions. For manipulation of source Rd files one can supply an Rd object obtained by parse_Rd-ying it.

FIXME: I wrote this function in a hurry when it turned out that the help system has changed in R version 2.10, needs clean up.

todo: In recent versions of R, help may return more than one file (see paths in this function's source), this needs to be handled.

Georgi N. Boshnakov

# 1st arg is name of a function
Rd_fun("data.frame",keep_section="\\arguments")
Rd_fun("seq",keep_section="\\arguments")

# 1st arg is the value of a call to help()
h1 <- help("seq")
class(h1)
Rd_fun(h1,keep_section="\\title") # note: in Rd file the number of
Rd_fun(h1,keep_section="\\arguments") # backslashes is twice that in
                                        # the rendered doc.

Loading required package: tools
\title{Data Frames}\name{data.frame}\arguments{
  \item{\dots}{these arguments are of either the form \code{value} or
    \code{tag = value}.  Component names are created based on the tag (if
    present) or the deparsed argument itself.}
  \item{row.names}{\code{NULL} or a single integer or character string
    specifying a column to be used as row names, or a character or
    integer vector giving the row names for the data frame.}
  \item{check.rows}{if \code{TRUE} then the rows are checked for
    consistency of length and names.}
  \item{check.names}{logical.  If \code{TRUE} then the names of the
    variables in the data frame are checked to ensure that they are
    syntactically valid variable names and are not duplicated.
    If necessary they are adjusted (by \code{\link{make.names}})
    so that they are.}
  \item{fix.empty.names}{logical indicating if arguments which are
    \dQuote{unnamed} (in the sense of not being formally called as
    \code{someName = arg}) get an automatically constructed name or
    rather name \code{""}.  Needs to be set to \code{FALSE} even when
    \code{check.names} is false if \code{""} names should be kept.}
  \item{stringsAsFactors}{logical: should character vectors be converted
    to factors?  The \sQuote{factory-fresh} default is \code{TRUE}, but
    this can be changed by setting \code{\link{options}(stringsAsFactors
      = FALSE)}.}
}\title{Sequence Generation}\name{seq}\arguments{
  \item{\dots}{arguments passed to or from methods.}
  \item{from, to}{the starting and (maximal) end values of the
    sequence.  Of length \code{1} unless just \code{from} is supplied as
    an unnamed argument.}
  \item{by}{number: increment of the sequence.}
  \item{length.out}{desired length of the sequence.  A
    non-negative number, which for \code{seq} and \code{seq.int} will be
    rounded up if fractional.}
  \item{along.with}{take the length from the length of this argument.}
}[1] "help_files_with_topic"
\title{Sequence Generation}\name{seq}\title{Sequence Generation}\name{seq}\arguments{
  \item{\dots}{arguments passed to or from methods.}
  \item{from, to}{the starting and (maximal) end values of the
    sequence.  Of length \code{1} unless just \code{from} is supplied as
    an unnamed argument.}
  \item{by}{number: increment of the sequence.}
  \item{length.out}{desired length of the sequence.  A
    non-negative number, which for \code{seq} and \code{seq.int} will be
    rounded up if fractional.}
  \item{along.with}{take the length from the length of this argument.}
}