help                  package:utils                  R Documentation

Documentation

Description:

     These functions provide access to documentation. Documentation on
     a topic with name 'name' (typically, an R object or a data set)
     can be displayed with either 'help("name")' or '?name'.

Usage:

     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

Arguments:

   topic: usually, a name or character string specifying the topic for
          which help is sought.  A character string (enclosed in
          explicit single or double quotes) is always taken as naming a
          topic.

          For 'help', if the value of 'topic' is a length-one character
          vector the topic is taken to be the value of the only
          element.  Otherwise 'topic' must be a name or a reserved word
          (if syntactically valid) or character string.

          For '?' the 'topic' argument may also be a function call, to
          ask for documentation on a corresponding method: see the
          section on S4 method documentation.  Unlike 'help', all names
          are deparsed to give the desired topic.  The forms
          'pkg::topic' and 'pkg:::topic' are treated specially, and
          look for help on 'topic' in package 'package'.

          See 'Details' for what happens if this is omitted for 'help'. 

 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.  If none is available, plain text
          help will be shown.

htmlhelp: logical (or 'NULL').  If 'TRUE' (which is the default after
          'help.start' has been called), the HTML version (if
          available) of the help on the topic will be shown in the
          browser specified by 'options("browser")'.  See 'browseURL'
          for details of the browsers that are supported.  Where
          possible an existing browser window is re-used.

   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.

Details:

     '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.)

     Some topics need to be quoted (by backticks) or given as a
     character string.  There include those which cannot syntactically
     appear on their own such  as unary and binary operators,
     'function' and control-flow reserved words (including 'if', 'else'
     'for', 'in', 'repeat', 'while', 'break' and 'next'.  The other
     'reserved' words can be used as if they were names, for example
     'TRUE', 'NA' and 'Inf'.

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

     HTML help works best if 'help.start()' has been called in the
     session.  Otherwise there will be a warning about 'Using
     non-linked HTML file: hyperlinks may be incorrect' and
     cross-library links will most likely not be resolved.

     If 'offline' is 'TRUE', hardcopy of the documentation is produced
     by running the LaTeX version of the help page through 'latex' and
     'dvips'.  Depending on your 'dvips' configuration, hardcopy will
     be sent to the printer or saved in a file.  If the programs are in
     non-standard locations and hence were not found at compile time,
     you can either set the options 'latexcmd' and 'dvipscmd', or the
     environment variables 'R_LATEXCMD' and 'R_DVIPSCMD' appropriately.
     The appearance of the output can be customized through a file
     'Rhelp.cfg' somewhere in your LaTeX search path: this will be
     input as a LaTeX style file after 'Rd.sty'.  Some  environment
     variables are consulted, notably 'R_PAPERSIZE' (_via_
     'getOption("papersize")') and 'R_RD4DVI'

     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.

S4 Method Documentation:

     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').

Note:

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

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'help.search()' or '??' 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.

Examples:

     help()
     help(help)              # the same

     help(lapply)
     ?lapply                 # the same

     help("for")             # or ?"for", but quotes/backticks 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"
     help(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)

