help {utils} | R Documentation |
These functions provide access to documentation.
Documentation on a topic with name name
(typically, an R
object or a data set) can be printed with either help(name)
or
?name
.
help(topic, offline = FALSE, package = NULL, lib.loc = NULL, verbose = getOption("verbose"), try.all.packages = getOption("help.try.all.packages"), chmhelp = getOption("chmhelp"), htmlhelp = getOption("htmlhelp"), pager = getOption("pager")) ?topic type?topic
topic |
usually, the name on which documentation is sought.
The name may be quoted or unquoted (but note that if topic
is the name of a variable containing a character string documentation
is provided for the name, not for the character string).
The topic argument may also be a function call, to ask for
documentation on a corresponding method. See the section on method
documentation.
See Details for what happens if this is omitted. |
offline |
a logical indicating whether documentation should be displayed on-line to the screen (the default) or hardcopy of it should be produced. |
package |
a name or character vector giving the packages to look
into for documentation, or NULL . By default, all packages
in the search path are used. |
lib.loc |
a character vector of directory names of R libraries,
or NULL . The default value of NULL corresponds to all
libraries currently known. If the default is used, the loaded
packages are searched before the libraries. |
verbose |
logical; if TRUE , the file name is reported. |
try.all.packages |
logical; see Note . |
chmhelp |
logical (or NULL ). Only relevant under Windows.
If TRUE the Compiled HTML version of the help on the topic
will be shown in a help viewer. |
htmlhelp |
logical (or NULL ). If TRUE , the HTML
version of the help on the topic will be shown in a browser specified by
options("browser") or the file-association mechanism.
|
pager |
the pager to be used for file.show . |
type |
the special type of documentation to use for this topic;
for example, if the type is class , documentation is
provided for the class with name topic . The function
topicName returns the actual name used in this case.
See the section on method documentation for the uses of
type to get help on formal methods. |
topic
is not optional: if it is omitted R will give a hint as
to suitable topics if a package is specified, to available packages if
lib.loc
only is specified, and help on help
itself if
nothing is specified. (In all cases this will be text help.)
In the case of unary and binary operators and control-flow special
forms (including if
, for
and function
), the topic
may need to be quoted.
If multiple help files matching topic
are found, in interactive
use a menu is presented for the user to choose one: otherwise the
first on the search path is used. (The menu will be a graphical menu
if possible if getOption("menu.graphics")
is true, the
default.)
If offline
is TRUE
, hardcopy of the documentation is
produced by running the LaTeX version of the help page through
latex
(note that LaTeX 2e is needed). You need to customize
the file ‘R_HOME/bin/helpPRINT.bat’ which contains an example.
The appearance of the output can be customized through a file
‘Rhelp.cfg’ somewhere in your LaTeX search path.
If LaTeX versions of help pages were not built at the installation of
the package, the print
method will ask if conversion with
R CMD Rdconv
(which requires Perl) should be attempted.
The authors of formal (‘S4’) methods can provide documentation
on specific methods, as well as overall documentation on the methods
of a particular function. The "?"
operator allows access to
this documentation in three ways.
The expression methods ? f
will look for the overall
documentation methods for the function f
. Currently, this
means the documentation file containing the alias f-methods
.
There are two different ways to look for documentation on a
particular method. The first is to supply the topic
argument
in the form of a function call, omitting the type
argument.
The effect is to look for documentation on the method that would be
used if this function call were actually evaluated. See the examples
below. If the function is not a generic (no S4 methods are defined
for it), the help reverts to documentation on the function name.
The "?"
operator can also be called with type
supplied
as "method"
; in this case also, the topic
argument is
a function call, but the arguments are now interpreted as specifying
the class of the argument, not the actual expression that will
appear in a real call to the function. See the examples below.
The first approach will be tedious if the actual call involves complicated expressions, and may be slow if the arguments take a long time to evaluate. The second approach avoids these difficulties, but you do have to know what the classes of the actual arguments will be when they are evaluated.
Both approaches make use of any inherited methods; the signature of
the method to be looked up is found by using selectMethod
(see the documentation for getMethod
).
Unless lib.loc
is specified explicitly, the loaded packages are
searched before those in the specified libraries. This ensures that
if a library is loaded from a library not in the known library trees,
then the help from the loaded library is used. If lib.loc
is
specified explicitly, the loaded packages are not searched.
If this search fails and argument try.all.packages
is
TRUE
and neither packages
nor lib.loc
is
specified, then all the packages in the known library trees are
searched for help on topic
and a list of (any) packages where
help may be found is printed (but no help is shown).
N.B. searching all packages can be slow.
The help files can be many small files. On some file systems it is desirable to save space, and the text files in the ‘help’ directory of an installed package can be zipped up as a zip archive ‘Rhelp.zip’. Ensure that file ‘AnIndex’ remains un-zipped. Similarly, all the files in the ‘latex’ directory can be zipped to ‘Rhelp.zip’. This is done on Windows for the larger packages.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
help.search()
for finding help pages on a “vague”
topic;
help.start()
which opens the HTML version of the R
help pages;
library()
for listing available packages and the
user-level objects they contain;
data()
for listing available data sets;
methods()
.
See prompt()
to get a prototype for writing help
pages of private packages.
help() help(help) # the same help(lapply) ?lapply # the same help("for") # or ?"for", but the quotes are needed ?"+" help(package="splines") # get help even when package is not loaded data() # list all available data sets ?women # information about data set "women" topi <- "women" ## Not run: help(topi) ##--> Error: No documentation for 'topi' try(help("bs", try.all.packages=FALSE)) # reports not found (an error) help("bs", try.all.packages=TRUE) # reports can be found in package 'splines' ## Not run: require(methods) ## define a S4 generic function and some methods combo <- function(x, y) c(x, y) setGeneric("combo") setMethod("combo", c("numeric", "numeric"), function(x, y) x+y) ## assume we have written some documentation for combo, and its methods .... ?combo ## produces the function documentation methods?combo ## looks for the overall methods documentation method?combo("numeric", "numeric") ## documentation for the method above ?combo(1:10, rnorm(10)) ## ... the same method, selected according to ## the arguments (one integer, the other numeric) ?combo(1:10, letters) ## documentation for the default method ## End(Not run)