1% File src/library/utils/man/help.search.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2014 R Core Team
4% Distributed under GPL 2 or later
5
6\name{help.search}
7\alias{help.search}
8\alias{??}
9\alias{print.hsearch}
10\title{Search the Help System}
11\description{
12  Allows for searching the help system for documentation matching a
13  given character string in the (file) name, alias, title, concept or
14  keyword entries (or any combination thereof), using either
15  \link{fuzzy matching} or \link{regular expression} matching.  Names
16  and titles of the matched help entries are displayed nicely formatted.
17
18  Vignette names, titles and keywords and demo names and titles
19  may also be searched.
20}
21\usage{
22help.search(pattern, fields = c("alias", "concept", "title"),
23            apropos, keyword, whatis, ignore.case = TRUE,
24            package = NULL, lib.loc = NULL,
25            help.db = getOption("help.db"),
26            verbose = getOption("verbose"),
27            rebuild = FALSE, agrep = NULL, use_UTF8 = FALSE,
28            types = getOption("help.search.types"))
29\special{??pattern}
30\special{field??pattern}
31}
32\arguments{
33  \item{pattern}{a character string to be matched in the specified
34    fields.  If this is given, the arguments \code{apropos},
35    \code{keyword}, and \code{whatis} are ignored.}
36  \item{fields}{a character vector specifying the fields of the help
37    database to be searched.  The entries must be abbreviations of
38    \code{"name"}, \code{"title"}, \code{"alias"}, \code{"concept"}, and
39    \code{"keyword"}, corresponding to the help page's (file) name, its
40    title, the topics and concepts it provides documentation for, and
41    the keywords it can be classified to.  See below for details and how
42    vignettes and demos are searched.}
43  \item{apropos}{a character string to be matched in the help page
44    topics and title.}
45  \item{keyword}{a character string to be matched in the help page
46    \sQuote{keywords}. \sQuote{Keywords} are really categories: the
47    standard categories are listed in file \file{R.home("doc")/KEYWORDS}
48    (see also the example) and some package writers have defined their
49    own.  If \code{keyword} is specified, \code{agrep} defaults to
50    \code{FALSE}.}  \item{whatis}{a character string to be matched in
51    the help page topics.}
52  \item{ignore.case}{a logical.  If \code{TRUE}, case is ignored during
53    matching; if \code{FALSE}, pattern matching is case sensitive.}
54  \item{package}{a character vector with the names of packages to
55    search through, or \code{NULL} in which case \emph{all} available
56    packages in the library trees specified by \code{lib.loc} are
57    searched.}
58  \item{lib.loc}{a character vector describing the location of \R
59    library trees to search through, or \code{NULL}.  The default value
60    of \code{NULL} corresponds to all libraries currently known.}
61  \item{help.db}{a character string giving the file path to a previously
62    built and saved help database, or \code{NULL}.}
63  \item{verbose}{logical; if \code{TRUE}, the search process is traced.
64    Integer values are also accepted, with \code{TRUE} being equivalent
65    to \code{2}, and \code{1} being less verbose.  On Windows a progress
66    bar is shown during rebuilding, and on Unix a heartbeat is shown for
67    \code{verbose = 1} and a package-by-package list for
68    \code{verbose >= 2}.}
69  \item{rebuild}{a logical indicating whether the help database should
70    be rebuilt.  This will be done automatically if \code{lib.loc} or
71    the search path is changed, or if \code{package} is used and a value
72    is not found.}
73  \item{agrep}{if \code{NULL} (the default unless \code{keyword} is
74    used) and the character string to
75    be matched consists of alphanumeric characters, whitespace or a dash
76    only, approximate (fuzzy) matching via \code{\link{agrep}} is used
77    unless the string has fewer than 5 characters; otherwise, it is
78    taken to contain a \link{regular expression} to be matched via
79    \code{\link{grep}}.  If \code{FALSE}, approximate matching is not
80    used.  Otherwise, one can give a numeric or a list specifying the
81    maximal distance for the approximate match, see argument
82    \code{max.distance} in the documentation for \code{\link{agrep}}.}
83  \item{use_UTF8}{logical: should results be given in UTF-8 encoding?
84    Also changes the meaning of regexps in \code{agrep} to be Perl regexps.}
85  \item{types}{a character vector listing the types of documentation
86    to search.  The entries must be abbreviations of \code{"vignette"}
87    \code{"help"} or \code{"demo"}. Results will be presented in the
88    order specified.}
89  \item{field}{a single value of \code{fields} to search.}
90}
91\details{
92  Upon installation of a package, a pre-built help.search index is
93  serialized as \file{hsearch.rds} in the \file{Meta} directory
94  (provided the package has any help pages).  Vignettes are also
95  indexed in the \file{Meta/vignette.rds} file.  These files are used to
96  create the help search database via \code{\link{hsearch_db}}.
97
98  The arguments \code{apropos} and \code{whatis} play a role similar to
99  the Unix commands with the same names.
100
101  Searching with \code{agrep = FALSE} will be several times faster than
102  the default (once the database is built).  However, approximate
103  searches should be fast enough (around a second with 5000 packages
104  installed).
105
106  If possible, the help database is saved in memory for use by
107  subsequent calls in the session.
108
109  Note that currently the aliases in the matching help files are not
110  displayed.
111
112  As with \code{\link{?}}, in \code{??} the pattern may be prefixed with a
113  package name followed by \code{::} or \code{:::} to limit the search
114  to that package.
115
116  For help files, \samp{\keyword} entries which are not among the
117  standard keywords as listed in file \file{KEYWORDS} in the \R
118  documentation directory are taken as concepts.  For standard keyword
119  entries different from \samp{internal}, the corresponding descriptions
120  from file \file{KEYWORDS} are additionally taken as concepts.  All
121  \samp{\concept} entries used as concepts.
122
123  Vignettes are searched as follows.  The \code{"name"} and
124  \code{"alias"} are both the base of the vignette filename, and the
125  \code{"concept"} entries are taken from the \code{\\VignetteKeyword}
126  entries.  Vignettes are not classified using the help system
127  \code{"keyword"} classifications.  Demos are handled
128  similarly to vignettes, without the \code{"concept"} search.
129}
130
131\value{
132  The results are returned in a list object of class \code{"hsearch"},
133  which has a print method for nicely formatting the results of the
134  query.  This mechanism is experimental, and may change in future
135  versions of \R.
136
137  In \code{R.app} on macOS, this will show up a browser with selectable
138  items. On exiting this browser, the help pages for the selected items
139  will be shown in separate help windows.
140
141  The internal format of the class is undocumented and subject to change.
142}
143\seealso{
144  \code{\link{hsearch_db}} for more information on the help search
145  database employed, and for utilities to inspect available concepts and
146  keywords.
147
148  \code{\link{help}};
149  \code{\link{help.start}} for starting the hypertext (currently HTML)
150  version of \R's online documentation, which offers a similar search
151  mechanism.
152
153  \code{\link{RSiteSearch}} to access an on-line search of \R resources.
154
155  \code{\link{apropos}} uses regexps and has nice examples.
156}
157\examples{
158help.search("linear models")    # In case you forgot how to fit linear
159                                # models
160help.search("non-existent topic")
161
162??utils::help  # All the topics matching "help" in the utils package
163
164\donttest{
165help.search("print")            # All help pages with topics or title
166                                # matching 'print'
167help.search(apropos = "print")  # The same
168
169help.search(keyword = "hplot")  # All help pages documenting high-level
170                                # plots.
171file.show(file.path(R.home("doc"), "KEYWORDS"))  # show all keywords
172
173## Help pages with documented topics starting with 'try'.
174help.search("\\\\btry", fields = "alias")
175}}
176\keyword{documentation}
177