\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 formatted.
\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.  This will be done automatically if \code{lib.loc} or
the search path is changed, or if \code{package} is used and a value
is not found.
\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 pre-built help.search index is
serialized as \file{hsearch.rds} in the \file{Meta} directory
(provided the package has any help pages).  These files are used to
create the data base.

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

Searching with \code{agrep = FALSE} will be several times faster
than the default.

If possible, the help data base is saved in memory or (if memory
limits have been set: see \code{\LinkA{mem.limits}{mem.limits}}) to a file in the
session temporary directory for use by subsequent calls in the
session.

Note that currently the aliases in the matching help files are not
displayed.

Matching by \code{agrep} is by bytes even in multi-byte locales:
character-by-character matching will be too slow with a thousand or
more packages.
\end{Details}
\begin{Value}
The results are returned in a list object of class \code{"hsearch"},
which has a print method for nicely formatting the results of the
query.  This mechanism is experimental, and may change in future
versions of \R.

The internal format of the class is undocumented and subject to change.
\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")
## End(Not run)\end{ExampleCode}
\end{Examples}

