\HeaderA{help}{Documentation}{help}
\aliasA{?}{help}{?}
\keyword{documentation}{help}
\begin{Description}\relax
These functions provide access to documentation.
Documentation on a topic with name \code{name} (typically, an \R{}
object or a data set) can be displayed with either \code{help("name")} or
\code{?name}.
\end{Description}
\begin{Usage}
\begin{verbatim}
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
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{topic}] usually, a \LinkA{name}{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 \code{help}, if the value of \code{topic} is a length-one
character vector the topic is taken to be the value of the only
element.  Otherwise \code{topic} must be a name or a \LinkA{reserved}{reserved}
word (if syntactically valid) or character string.

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

See \sQuote{Details} for what happens if this is omitted for \code{help}.

\item[\code{offline}] a logical indicating whether documentation should be
displayed on-line to the screen (the default) or hardcopy of it
should be produced.
\item[\code{package}] a name or character vector giving the packages to look
into for documentation, or \code{NULL}.  By default, all packages
in the search path are used.
\item[\code{lib.loc}] a character vector of directory names of \R{} libraries,
or \code{NULL}.  The default value of \code{NULL} corresponds to all
libraries currently known.  If the default is used, the loaded
packages are searched before the libraries.
\item[\code{verbose}] logical; if \code{TRUE}, the file name is reported.
\item[\code{try.all.packages}] logical; see \code{Note}.
\item[\code{chmhelp}] logical (or \code{NULL}). Only relevant under Windows.
If \code{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.
\item[\code{htmlhelp}] logical (or \code{NULL}).  If \code{TRUE} (which is the
default after \code{\LinkA{help.start}{help.start}} has been called), the HTML
version (if available) of the help on the topic will be shown in the
browser specified by \code{options("browser")}.  See
\code{\LinkA{browseURL}{browseURL}} for details of the browsers that are
supported.  Where possible an existing browser window is re-used.
\item[\code{pager}] the pager to be used for \code{\LinkA{file.show}{file.show}}.
\item[\code{type}] the special type of documentation to use for this topic;
for example, if the type is \code{class}, documentation is
provided for the class with name \code{topic}.  The function
\code{topicName} returns the actual name used in this case.
See the section on method documentation for the uses of
\code{type} to get help on formal methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{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
\code{lib.loc} only is specified, and help on \code{help} itself if
nothing is specified.  (In all cases this will be text help.)

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

If multiple help files matching \code{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 \code{\LinkA{getOption}{getOption}("menu.graphics")} is true, the
default.)

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

If \code{offline} is \code{TRUE}, hardcopy of the documentation is
produced by running the LaTeX version of the help page through
\code{latex} and \code{dvips}.  Depending on your \code{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
\code{latexcmd} and \code{dvipscmd}, or the environment variables
\env{R\_LATEXCMD} and \env{R\_DVIPSCMD} appropriately.
The appearance of the output can be customized through a file
\file{Rhelp.cfg} somewhere in your LaTeX search path: this will be
input as a LaTeX style file after \code{Rd.sty}.  Some 
\LinkA{environment variables}{environment variables} are consulted, notably \env{R\_PAPERSIZE}
(\emph{via} \code{getOption("papersize")}) and \env{R\_RD4DVI}

If LaTeX versions of help pages were not built at the installation of
the package, the \code{print} method will ask if conversion with
\code{R CMD Rdconv} (which requires Perl) should be attempted.
\end{Details}
\begin{Section}{S4 Method Documentation}
The authors of formal (\sQuote{S4}) methods can provide documentation
on specific methods, as well as overall documentation on the methods
of a particular function.  The \code{"?"} operator allows access to
this documentation in three ways.

The expression \code{methods ? f} will look for the overall
documentation methods for the function \code{f}.  Currently, this
means the documentation file containing the alias \code{f-methods}.

There are two different ways to look for documentation on a
particular method.  The first is to supply the \code{topic} argument
in the form of a function call, omitting the \code{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 \code{"?"} operator can also be called with \code{type} supplied
as \code{"method"}; in this case also, the \code{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 \code{selectMethod}
(see the documentation for  \code{\LinkA{getMethod}{getMethod}}).
\end{Section}
\begin{Note}\relax
Unless \code{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 \code{lib.loc} is
specified explicitly, the loaded packages are \emph{not} searched.

If this search fails and argument \code{try.all.packages} is
\code{TRUE} and neither \code{packages} nor \code{lib.loc} is
specified, then all the packages in the known library trees are
searched for help on \code{topic} and a list of (any) packages where
help may be found is printed (but no help is shown).
\bold{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 \file{help} directory
of an installed package can be zipped up as a zip archive
\file{Rhelp.zip}.  Ensure that file \file{AnIndex} remains un-zipped.
Similarly, all the files in the \file{latex} directory can be zipped
to \file{Rhelp.zip}.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{help.search}{help.search}()} or \code{\LinkA{??}{??}} for finding help pages on a vague
topic;
\code{\LinkA{help.start}{help.start}()} which opens the HTML version of the \R{}
help pages;
\code{\LinkA{library}{library}()} for listing available packages and the
user-level objects they contain;
\code{\LinkA{data}{data}()} for listing available data sets;
\code{\LinkA{methods}{methods}()}.

See \code{\LinkA{prompt}{prompt}()} to get a prototype for writing \code{help}
pages of private packages.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)\end{ExampleCode}
\end{Examples}

