help.search               package:base               R Documentation

_S_e_a_r_c_h _t_h_e _H_e_l_p _S_y_s_t_e_m

_D_e_s_c_r_i_p_t_i_o_n:

     Allows for searching the help system for documentation matching a
     given character string in the (file) name, alias, title, or
     keyword entries (or any combination thereof), using either fuzzy
     matching or regular expression matching.  Names and titles of the
     matched help entries are nicely displayed.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

 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.

  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.

   agrep: if 'NULL' (the default) 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'.

_D_e_t_a_i_l_s:

     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, is computed from the Rd files in the
     package and serialized as 'Rd.rds' in the 'Meta' subdirectory of
     the top-level package installation directory (or, prior to R 1.7,
     as '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 'hsearch.rds' in the 'Meta' directory, is the data
     base searched by 'help.search()'.

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

     If possible, the help data base is saved to the file 'help.db' in
     the '.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.

_V_a_l_u_e:

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

_S_e_e _A_l_s_o:

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

     'apropos' uses regexps and has nice examples.

_E_x_a_m_p_l_e_s:

     help.search("linear models")    # In case you forgot how to fit linear
                                     # models
     help.search("non-existent topic")
     ## Don't 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.

     ## 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 Don't run

