help.search              package:utils              R Documentation

Search the Help System

Description:

     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
     fuzzy matching or regular expression matching.  Names and titles
     of the matched help entries are displayed nicely formatted.

Usage:

     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)

Arguments:

 pattern: a character string to be matched in the specified fields.  If
          this is given, the arguments 'apropos', 'keyword', and
          'whatis' are ignored.

  fields: a character vector specifying the fields of the help data
          bases to be searched.  The entries must be abbreviations of
          '"name"', '"title"', '"alias"', '"concept"', and '"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.

 apropos: a character string to be matched in the help page topics and
          title.

 keyword: a character string to be matched in the help page 'keywords'.
          'Keywords' are really categories: the standard categories are
          listed in file 'RHOME/doc/KEYWORDS' (see also the example)
          and some package writers have defined their own.  If
          'keyword' is specified, 'agrep' defaults to 'FALSE'.

  whatis: a character string to be matched in the help page topics.

ignore.case: a logical.  If 'TRUE', case is ignored during matching; if
          'FALSE', pattern matching is case sensitive.

 package: a character vector with the names of packages to search
          through, or 'NULL' in which case _all_ available packages in
          the library trees specified by 'lib.loc' are searched.

 lib.loc: a character vector describing the location of R library trees
          to search through, or 'NULL'.  The default value of 'NULL'
          corresponds to all libraries currently known.

 help.db: a character string giving the file path to a previously built
          and saved help data base, or 'NULL'.

 verbose: logical; if 'TRUE', the search process is traced.

 rebuild: a logical indicating whether the help data base should be
          rebuilt.  This will be done automatically if 'lib.loc' or the
          search path is changed, or if 'package' is used and a value
          is not found.

   agrep: if 'NULL' (the default unless 'keyword' is used) and the
          character string to be matched consists of alphanumeric
          characters, whitespace or a dash only, approximate (fuzzy)
          matching via 'agrep' is used unless the string has fewer than
          5 characters; otherwise, it is taken to contain a regular
          expression to be matched via 'grep'.  If '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 'max.distance' in the documentation for
          'agrep'.

Details:

     Upon installation of a package, a pre-built help.search index is
     serialized as 'hsearch.rds' in the 'Meta' directory (provided the
     package has any help pages).  These files are used to create the
     data base.

     The arguments 'apropos' and 'whatis' play a role similar to the
     Unix commands with the same names.

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

Value:

     The results are returned in a list object of class '"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.

See Also:

     'help'; 'help.start' for starting the hypertext (currently HTML)
     version of R's online documentation, which offers a similar search
     mechanism.

     'RSiteSearch' to access an on-line search of R resources.

     'apropos' uses regexps and has nice examples.

Examples:

     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)

