Rd_fun: Return all or selected sections of a help topic as an Rd...

In gbRd: Utilities for Processing Rd Objects and Files

Return all or selected sections of a help topic as an Rd object

Description

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.

Usage

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

Arguments

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.

Details

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.

Value

an Rd object

Note

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.

Author(s)

Georgi N. Boshnakov

Examples

# 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.

gbRd documentation built on June 22, 2024, 11:34 a.m.