Rdutils                package:tools                R Documentation

_R_d _U_t_i_l_i_t_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Utilities for computing on the information in Rd objects.

_U_s_a_g_e:

     Rd_db(package, dir, lib.loc = NULL)
     Rd_parse(file, text = NULL)

_A_r_g_u_m_e_n_t_s:

 package: a character string naming an installed package.

     dir: a character string specifying the path to a package's root
          source directory.  This should contain the subdirectory 'man'
          with R documentation sources (in Rd format).  Only used if
          'package' is not given.

 lib.loc: a character vector of directory names of R libraries, or
          'NULL'.  The default value of 'NULL' corresponds to all
          libraries currently known.  The specified library trees are
          used to search for 'package'.

    file: a connection, or a character string giving the name of a file
          or a URL to read documentation in Rd format from.

    text: character vector with documentation in Rd format. Elements
          are treated as if they were lines of a file.

_D_e_t_a_i_l_s:

     'Rd_db' builds a simple database of all Rd sources in a package,
     as a list of character vectors with the lines of the Rd files in
     the package.  This is particularly useful for working on installed
     packages, where the individual Rd files in the sources are no
     longer available.

     'Rd_parse' is a simple top-level Rd parser/analyzer.  It returns a
     list with components

     '_m_e_t_a' a list containing the Rd metadata (aliases, concepts,
          keywords, and documentation type);

     '_d_a_t_a' a data frame with the names ('tags') and corresponding text
          ('vals') of the top-level sections in the R documentation
          object;

     '_r_e_s_t' top-level text not accounted for (currently, silently
          discarded by Rdconv, and hence usually the indication of a
          problem).


     Note that at least for the time being, only the top-level
     structure is analyzed.

_W_a_r_n_i_n_g:

     These functions are still experimental.  Names, interfaces and
     values might change in future versions.

_S_e_e _A_l_s_o:

     'parse_Rd', an experimental parser.

_E_x_a_m_p_l_e_s:

     ## Build the Rd db for the (installed) base package.
     db <- Rd_db("base")
     ## Run Rd_parse on all entries in the Rd db.
     db <- lapply(db, function(txt) Rd_parse(text = txt))
     ## Extract the metadata.
     meta <- lapply(db, "[[", "meta")

     ## Keyword metadata per Rd file.
     keywords <- lapply(meta, "[[", "keywords")
     ## Tabulate the keyword entries.
     kw_table <- sort(table(unlist(keywords)))
     ## The 5 most frequent ones:
     rev(kw_table)[1 : 5]
     ## The "most informative" ones:
     kw_table[kw_table == 1]

     ## Concept metadata per Rd file.
     concepts <- lapply(meta, "[[", "concepts")
     ## How many files already have \concept metadata?
     sum(sapply(concepts, length) > 0)
     ## How many concept entries altogether?
     length(unlist(concepts))