\HeaderA{help.search}{Search the Help System}{help.search}
\aliasA{print.hsearch}{help.search}{print.hsearch}
\keyword{documentation}{help.search}
\begin{Description}\relax
Allows for searching the help system for documentation matching a
given character string in the (file) name, alias, title, concept or
keyword entries (or any combination thereof), using either
\LinkA{fuzzy matching}{fuzzy matching} or \LinkA{regular expression}{regular expression} matching.  Names
and titles of the matched help entries are displayed nicely.
\end{Description}
\begin{Usage}
\begin{verbatim}
help.search(pattern, fields = c("alias", "concept", "title"),
            apropos, keyword, whatis, ignore.case = TRUE,
            package = NULL, lib.loc = NULL,
            help.db = getOption("help.db"),
            verbose = getOption("verbose"),
            rebuild = FALSE, agrep = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{pattern}] a character string to be matched in the specified
fields.  If this is given, the arguments \code{apropos},
\code{keyword}, and \code{whatis} are ignored.
\item[\code{fields}] a character vector specifying the fields of the help
data bases to be searched.  The entries must be abbreviations of
\code{"name"}, \code{"title"}, \code{"alias"}, \code{"concept"}, and
\code{"keyword"}, corresponding to the help page's (file) name, its
title, the topics and concepts it provides documentation for, and
the keywords it can be classified to.
\item[\code{apropos}] a character string to be matched in the help page
topics and title.
\item[\code{keyword}] a character string to be matched in the help page
\sQuote{keywords}. \sQuote{Keywords} are really categories: the
standard categories are listed in file \file{RHOME/doc/KEYWORDS}
(see also the example) and some package writers have defined their
own.  If \code{keyword} is specified, \code{agrep} defaults to
\code{FALSE}.
\item[\code{whatis}] a character string to be matched in
the help page topics.
\item[\code{ignore.case}] a logical.  If \code{TRUE}, case is ignored during
matching; if \code{FALSE}, pattern matching is case sensitive.
\item[\code{package}] a character vector with the names of packages to
search through, or \code{NULL} in which case \emph{all} available
packages in the library trees specified by \code{lib.loc} are
searched.
\item[\code{lib.loc}] a character vector describing the location of \R{}
library trees to search through, or \code{NULL}.  The default value
of \code{NULL} corresponds to all libraries currently known.
\item[\code{help.db}] a character string giving the file path to a previously
built and saved help data base, or \code{NULL}.
\item[\code{verbose}] logical; if \code{TRUE}, the search process is traced.
\item[\code{rebuild}] a logical indicating whether the help data base should
be rebuilt.
\item[\code{agrep}] if \code{NULL} (the default unless \code{keyword} is
used) and the character string to
be matched consists of alphanumeric characters, whitespace or a dash
only, approximate (fuzzy) matching via \code{\LinkA{agrep}{agrep}} is used
unless the string has fewer than 5 characters; otherwise, it is
taken to contain a \LinkA{regular expression}{regular expression} to be matched via
\code{\LinkA{grep}{grep}}.  If \code{FALSE}, approximate matching is not
used.  Otherwise, one can give a numeric or a list specifying the
maximal distance for the approximate match, see argument
\code{max.distance} in the documentation for \code{\LinkA{agrep}{agrep}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Upon installation of a package, a contents data base which contains
the information on name, title, aliases and keywords and, concepts
starting with \R{} 1.8.0, is computed from the Rd files in the package and
serialized as \file{Rd.rds} in the \file{Meta} subdirectory of the
top-level package installation directory (or, prior to \R{} 1.7.0, as
\file{CONTENTS} in Debian Control Format with aliases and keywords
collapsed to character strings in the top-level package installation
directory).  This, or a pre-built help.search index serialized as
\file{hsearch.rds} in the \file{Meta} directory, is the data base
searched by \code{help.search()}.

The arguments \code{apropos} and \code{whatis} play a role similar to
the Unix commands with the same names.

If possible, the help data base is saved to the file \file{help.db} in
the \file{.R} subdirectory of the user's home directory or the current
working directory.

Note that currently, the aliases in the matching help files are not
displayed.
\end{Details}
\begin{Value}
The results are returned in an object of class \code{"hsearch"}, which
has a print method for nicely displaying the results of the query.
This mechanism is experimental, and may change in future versions of
R.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{help}{help}};
\code{\LinkA{help.start}{help.start}} for starting the hypertext (currently HTML)
version of \R's online documentation, which offers a similar search
mechanism.

\code{\LinkA{RSiteSearch}{RSiteSearch}} to access an on-line search of \R{} resources.

\code{\LinkA{apropos}{apropos}} uses regexps and has nice examples.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
help.search("linear models")    # In case you forgot how to fit linear
                                # models
help.search("non-existent topic")
## Not run: 
help.search("print")            # All help pages with topics or title
                                # matching 'print'
help.search(apropos = "print")  # The same

help.search(keyword = "hplot")  # All help pages documenting high-level
                                # plots.
file.show(file.path(R.home(), "doc", "KEYWORDS"))  # show all keywords

## Help pages with documented topics starting with 'try'.
help.search("\\btry", fields = "alias")
## Do not use '^' or '$' when matching aliases or keywords
## (unless all packages were installed using R 1.7 or newer).
## End(Not run)
\end{ExampleCode}
\end{Examples}