| % File src/library/utils/man/hsearch-utils.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{hsearch-utils} |
| \alias{hsearch_db} |
| \alias{hsearch_db_concepts} |
| \alias{hsearch_db_keywords} |
| \title{Help Search Utilities} |
| \description{ |
| Utilities for searching the help system. |
| } |
| \usage{ |
| hsearch_db(package = NULL, lib.loc = NULL, |
| types = getOption("help.search.types"), |
| verbose = getOption("verbose"), |
| rebuild = FALSE, use_UTF8 = FALSE) |
| hsearch_db_concepts(db = hsearch_db()) |
| hsearch_db_keywords(db = hsearch_db()) |
| } |
| \arguments{ |
| \item{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{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{types}{a character vector listing the types of documentation |
| to search. |
| See \code{\link{help.search}} for details.} |
| \item{verbose}{a logical controlling the verbosity of building the |
| help search database. |
| See \code{\link{help.search}} for details.} |
| \item{rebuild}{a logical indicating whether the help search database |
| should be rebuilt. |
| See \code{\link{help.search}} for details.} |
| \item{use_UTF8}{logical: should results be given in UTF-8 encoding?} |
| \item{db}{a help search database as obtained by calls to |
| \code{hsearch_db()}.} |
| } |
| \details{ |
| \code{hsearch_db()} builds and caches the help search database for |
| subsequent use by \code{\link{help.search}}. (In fact, re-builds only |
| when forced (\code{rebuild = TRUE}) or \dQuote{necessary}.) |
| |
| The format of the help search database is still experimental, and may |
| change in future versions. Currently, it consists of four tables: one |
| with base information about all documentation objects found, including |
| their names and titles and unique ids; three more tables contain the |
| individual aliases, concepts and keywords together with the ids of the |
| documentation objects they belong to. Separating out the latter three |
| tables accounts for the fact that a single documentation object may |
| provide several of these entries, and allows for efficient searching. |
| |
| See the details in \code{\link{help.search}} for how searchable |
| entries are interpreted according to help type. |
| |
| \code{hsearch_db_concepts()} and \code{hsearch_db_keywords()} extract |
| all concepts or keywords, respectively, from a help search database, |
| and return these in a data frame together with their total frequencies |
| and the numbers of packages they are used in, with entries sorted in |
| decreasing total frequency. |
| } |
| \examples{ |
| db <- hsearch_db() |
| ## Total numbers of documentation objects, aliases, keywords and |
| ## concepts (using the current format): |
| sapply(db, NROW) |
| ## Can also be obtained from print method: |
| db |
| ## 10 most frequent concepts: |
| head(hsearch_db_concepts(), 10) |
| ## 10 most frequent keywords: |
| head(hsearch_db_keywords(), 10) |
| } |
| \keyword{documentation} |