Getting Help and Documentation

# Text help goes to the pager. A pager can be a function, so print the file
# (removing the overstrike marks that underline the headings) and capture it.
options(pager = \(files, ...) {
  writeLines(gsub("_\b", "", readLines(files), fixed = TRUE))
})
help_lines <- \(topic) capture.output(help(topic))
page <- help_lines("read.csv")

# The first line names the Rd file (read.table), the package and the format.
page[1]
#> [1] "read.table                package:utils                R Documentation"
# The second paragraph is the title; headings end with a colon.
page[3]
#> [1] "Data Input"
grep("^[[:alpha:]][[:alpha:] ]*:$", page, value = TRUE)
#>  [1] "Description:"  "Usage:"        "Arguments:"    "Details:"
#>  [5] "Value:"        "CSV files:"    "Memory usage:" "Note:"
#>  [9] "References:"   "See Also:"     "Examples:"

# Usage: one page documents five functions; these are two of the entries.
usage <- page[(grep("^Usage:", page) + 1L):(grep("^Arguments:", page) - 1L)]
cat(usage[2L:3L], sep = "\n")
#>      read.table(file, header = FALSE, sep = "", quote = "\"'",
#>                 dec = ".", numerals = c("allow.loss", "warn.loss", "no.loss"),
first <- grep("^ +read\\.csv\\(", usage)
cat(usage[first:(first + 1L)], sep = "\n")
#>      read.csv(file, header = TRUE, sep = ",", quote = "\"",
#>               dec = ".", fill = TRUE, comment.char = "", ...)

# A generic with methods lists them with the class they are for.
summary_page <- help_lines("summary")
at <- grep("S3 method for class 'data.frame'", summary_page)
cat(summary_page[at:(at + 2L)], sep = "\n")
#>      ## S3 method for class 'data.frame'
#>      summary(object, maxsum = 7,
#>              digits = max(3, getOption("digits")-3), ...)

# Arguments: each entry starts with the argument name and a colon.
at <- grep("^ +header:", page)
cat(page[at:(at + 4L)], sep = "\n")
#>   header: a logical value indicating whether the file contains the
#>           names of the variables as its first line.  If missing, the
#>           value is determined from the file format: ‘header’ is set to
#>           ‘TRUE’ if and only if the first row contains one fewer field
#>           than the number of columns.

# Value and Examples are the sections to read last, and run first.
at <- grep("^Value:", page)
cat(page[(at + 2L):(at + 3L)], sep = "\n")
#>      A data frame (‘data.frame’) containing a representation of the
#>      data in the file.

read.table                package:utils                R Documentation

Data Input

Description:

     Reads a file in table format and creates a data frame from it,
     with cases corresponding to lines and variables to fields in the
     file.

Usage:

     read.table(file, header = FALSE, sep = "", quote = "\"'",
                [...]
     read.csv(file, header = TRUE, sep = ",", quote = "\"",
              dec = ".", fill = TRUE, comment.char = "", ...)
     [...]
Arguments:

    file: the name of the file which the data are to be read from.
          Each row of the table appears as one line of the file.  If it
          does not contain an _absolute_ path, the file name is
          _relative_ to the current working directory, ‘getwd()’.
  [...]
  header: a logical value indicating whether the file contains the
          names of the variables as its first line.  If missing, the
          value is determined from the file format: ‘header’ is set to
          ‘TRUE’ if and only if the first row contains one fewer field
          than the number of columns.
  [...]
     ...: Further arguments to be passed to ‘read.table’.

Value:

     A data frame (‘data.frame’) containing a representation of the
     data in the file.

# help() returns the path of the Rd file that documents a topic. Its base
# name is the page name, which is not always the name of the function.
topics <- c("read.csv", "if", "+", "[[", "%in%", "?", "??", "women")
pages <- vapply(topics, \(topic) basename(help(topic)), character(1L))
data.frame(topic = topics, page = unname(pages))
#>      topic        page
#> 1 read.csv  read.table
#> 2       if     Control
#> 3        +  Arithmetic
#> 4       [[     Extract
#> 5     %in%       match
#> 6        ?    Question
#> 7       ?? help.search
#> 8    women       women

# Overview pages of packages and S4 classes have their own topic names.
basename(help("stats-package"))
#> [1] "stats-package"
basename(help("data.frame-class"))
#> [1] "setOldClass"

# A variable holding a single string works as a topic (see the Arguments
# section of ?help); parentheses are the documented way to force it.
topic <- "mean"
basename(help((topic)))
#> [1] "mean"

# A topic that does not exist: the message is printed, not signalled.
capture.output(help("foo"))
#> [1] "No documentation for ‘foo’ in specified packages and libraries:"
#> [2] "you could try ‘??foo’"

# Restrict the search to one package, or look in every installed package.
basename(help("lm", package = "stats"))
#> [1] "lm"
x <- capture.output(help("read_csv", try.all.packages = TRUE))
sub("/.*$", "<library>", x[nzchar(x)])
#> [1] "Help for topic ‘read_csv’ is not in any loaded package but can be found"
#> [2] "in the following packages:"
#> [3] "  Package               Library"
#> [4] "  readr                 <library>"

# help(package =) describes a package: its DESCRIPTION fields, the index of
# its help pages and its vignettes, even when the package is not loaded.
info <- help(package = "stats")
class(info)
#> [1] "packageInfo"
info$info[[1L]][1:4]
#> [1] "Package:            stats"
#> [2] "Version:            4.6.1"
#> [3] "Priority:           base"
#> [4] "Title:              The R Stats Package"
grep("^lm  ", info$info[[2L]], value = TRUE)
#> [1] "lm                      Fitting Linear Models"
info$info[[3L]]
#>      [,1]      [,2]
#> [1,] "reshape" "Using the reshape function (source, pdf)"

# The kind of help is chosen by help_type; the option is unset here and the
# result of help() records the type it used (text under Rscript).
getOption("help_type")
#> NULL
attr(help("lm"), "type")
#> [1] "text"

?read.csv                              # text, HTML or IDE pane, depending on help_type
?"if"                                  # reserved words need quotes
?"[["                                  # so do operators; backticks work as well
?utils::read.csv                       # one package only
package?stats                          # the overview page of a package
help("read.csv", help_type = "html")   # force HTML help
help("lm", package = "stats")          # look in one package, loaded or not
help(package = "stats")                # index of a package

help.start()                   # the HTML help system in the browser
help.start(update = TRUE)      # rebuild the package index first

# Search results are shown by the pager, as help pages are: make it print.
options(pager = \(files, ...) writeLines(readLines(files)))

# Search the help system: fuzzy matching tolerates typing mistakes.
hs <- help.search("lenear model", package = "stats", types = "help")
x <- capture.output(print(hs))
cat(head(x[nzchar(x)], 9L), sep = "\n")
#> Help files with alias or concept or title matching ‘lenear model’ using
#> fuzzy matching:
#> stats::anova.glm        Analysis of Deviance for Generalized Linear
#>                         Model Fits
#> stats::anova.lm         ANOVA for Linear Model Fits
#> stats::anova.mlm        Comparisons between Multivariate Linear Models
#> stats::family.glm       Accessing Generalized Linear Model Fits
#> stats::family.lm        Accessing Linear Model Fits
#> stats::glm              Fitting Generalized Linear Models

# Patterns shorter than five characters are regular expressions, not fuzzy.
hs <- help.search("csv", package = "utils", fields = "alias")
x <- capture.output(print(hs))
cat(head(x[nzchar(x)], 7L), sep = "\n")
#> Help files with alias matching ‘csv’ using regular expression matching:
#> utils::read.table       Data Input
#>   Aliases: read.csv, read.csv2
#> utils::write.table      Data Output
#>   Aliases: write.csv, write.csv2
#> Type '?PKG::FOO' to inspect entries 'PKG::FOO', or 'TYPE?PKG::FOO' for
#> entries like 'PKG::FOO-TYPE'.

# agrep = FALSE turns fuzzy matching off.
x <- capture.output(print(help.search("lenear", package = "stats",
                                      agrep = FALSE)))
cat(x, sep = "\n")
#> No vignettes or demos or help files found with alias or concept or
#> title matching ‘lenear’ using regular expression matching.

# apropos() matches object names on the search path with a regular expression.
apropos("^read\\.")
#>  [1] "read.csv"     "read.csv2"    "read.dcf"     "read.delim"   "read.delim2"
#>  [6] "read.DIF"     "read.fortran" "read.ftable"  "read.fwf"     "read.socket"
#> [11] "read.table"
apropos("^read", mode = "function") |> length()
#> [1] 18
apropos("GLM")
#> [1] "glm"           "glm.control"   "glm.fit"       "predict.glm"
#> [5] "residuals.glm" "summary.glm"
apropos("GLM", ignore.case = FALSE)
#> character(0)

# find() says where one exact name lives; numeric = TRUE gives the position.
find("read.csv")
#> [1] "package:utils"
find("read.csv", numeric = TRUE)
#> package:utils
#>             5
find("sd")
#> [1] "package:stats"
find("no_such_function")
#> character(0)

RSiteSearch("{generalized linear model}")                 # a phrase, all areas
RSiteSearch("read csv", restrict = "Rfunctions")          # base R help pages only
RSiteSearch("csv", restrict = c("functions", "vignettes"), words = "any")

books <- read.csv("books.csv")

args(read.csv)
#> function (file, header = TRUE, sep = ",", quote = "\"", dec = ".",
#>     fill = TRUE, comment.char = "", ...)
#> NULL
formals(read.csv)$sep
#> [1] ","
str(books)
#> 'data.frame':	16 obs. of  6 variables:
#>  $ title : chr  "The Dispossessed" "Pride and Prejudice" "  the quiet streets " "Loud Roofs" ...
#>  $ author: chr  "Ursula K. Le Guin" "Jane Austen" "Mara Quill" "Mara Quill" ...
#>  $ isbn  : chr  "978-0-306-40615-7" "978-0-14-143951-8" "9780001000100" "978-0-00-200029-1" ...
#>  $ year  : int  1974 1813 2019 2021 2016 2008 NA 1999 2012 2023 ...
#>  $ genre : chr  "Science fiction" "Classic" "Fiction" "fiction" ...
#>  $ pages : int  387 432 214 198 301 NA 96 280 352 256 ...

# Typing a name prints its source. Drop the bytecode address, which changes.
src <- capture.output(print(sd))
src[!grepl("^<bytecode", src)]
#> [1] "function (x, na.rm = FALSE) "
#> [2] "sqrt(var(if (is.vector(x) || is.factor(x)) x else as.double(x), "
#> [3] "    na.rm = na.rm))"
#> [4] "<environment: namespace:stats>"

# S3 methods are hidden in namespaces: methods() lists them, getS3method()
# and getAnywhere() find them (R FAQ 7.26 and 7.40).
m <- methods("summary")
head(format(m), 6L)
#> [1] "summary.aov"                    "summary.aovlist*"
#> [3] "summary.aspell*"                "summary.check_packages_in_dir*"
#> [5] "summary.connection"             "summary.data.frame"
head(attr(m, "info"), 3L)
#>                 visible                            from generic  isS4
#> summary.aov        TRUE                           stats summary FALSE
#> summary.aovlist   FALSE registered S3method for summary summary FALSE
#> summary.aspell    FALSE registered S3method for summary summary FALSE
args(getS3method("summary", "data.frame"))
#> function (object, maxsum = 7L, digits = max(3L, getOption("digits") -
#>     3L), ...)
#> NULL
where <- getAnywhere("summary.data.frame")
where$where
#> [1] "package:base"
#> [2] "registered S3 method for summary from namespace base"
#> [3] "namespace:base"
where$visible
#> [1]  TRUE FALSE FALSE

# example() runs the Examples section of a help page. apropos has \dontrun
# and \donttest parts; the echoed lines start with the prompt "aprops>".
out <- capture.output(example(apropos, ask = FALSE))
cat(head(out[nzchar(out)], 8L), sep = "\n")
#> aprops> require(stats)
#> aprops> ## Not run: apropos("lm")
#> aprops> apropos("GLM")                      # several
#> [1] "glm"           "glm.control"   "glm.fit"       "predict.glm"
#> [5] "residuals.glm" "summary.glm"
#> aprops> apropos("GLM", ignore.case = FALSE) # not one
#> character(0)
#> aprops> apropos("lq")

# \dontrun code is shown as a comment unless run.dontrun = TRUE, and
# \donttest code is skipped unless run.donttest is TRUE (interactive() is
# the default, so it is skipped here: its lines are echoed as "##D").
cat(grep("Not run|No test", out, value = TRUE), sep = "\n")
#> aprops> ## Not run: apropos("lm")
#> aprops> ## Not run: apropos(".", mode = "list")  # includes many datasets
#> aprops> ## No test:
#> aprops> ## End(No test)
out <- capture.output(example(apropos, run.dontrun = TRUE, ask = FALSE))
cat(grep("apropos\\(\"lm\"\\)", out, value = TRUE), sep = "\n")
#> aprops> apropos("lm")

# demo() lists the demonstrations of the loaded packages as a packageIQR.
demos <- demo(package = "stats")
class(demos)
#> [1] "packageIQR"
demos$results[, "Item"]
#> [1] "glm.vr" "lm.glm" "nlm"    "smooth"

# vignette() lists the long-form guides of installed packages.
v <- vignette(package = "dplyr")
data.frame(item = v$results[, "Item"],
           title = sub(" \\(source.*$", "", v$results[, "Title"])) |>
  head(4L)
#>       item                  title
#> 1  colwise Column-wise operations
#> 2     base       dplyr <-> base R
#> 3 grouping           Grouped data
#> 4    dplyr  Introduction to dplyr
v1 <- vignette("grid", package = "grid")
class(v1)
#> [1] "vignette"
c(v1$Package, v1$Topic, v1$PDF)
#> [1] "grid"     "grid"     "grid.pdf"
vignette(package = "grid")$results[, "Item"]
#>  [1] "moveline"    "displaylist" "interactive" "frame"       "grid"
#>  [6] "locndimn"    "sharing"     "nonfinite"   "saveload"    "rotated"
#> [11] "grobs"       "viewports"   "plotexample"

demo()                                    # demos of the loaded packages
demo(package = "stats")                   # demos of one package
demo(lm.glm, package = "stats", ask = FALSE)   # run one without pausing

browseVignettes()                    # all installed packages, in a browser
browseVignettes("dplyr")             # one package
vignette("dplyr", package = "dplyr") # open one
RShowDoc("frame", package = "grid")  # a rendered vignette, pdf or html

RShowDoc("R-intro")                  # pdf in a batch run, html when interactive
RShowDoc("R-lang", type = "html")    # choose the format
RShowDoc("FAQ", type = "txt")        # the R FAQ as text, through the pager
RShowDoc("NEWS")                     # the NEWS file of this R

# The files that RShowDoc() can open sit in R.home("doc") of an installation;
# which formats of the manuals exist depends on how R was built.
list.files(R.home("doc"), pattern = "^[A-Z]+$")
#> [1] "AUTHORS"    "COPYING"    "COPYRIGHTS" "FAQ"        "KEYWORDS"
#> [6] "NEWS"       "RESOURCES"  "THANKS"
list.files(file.path(R.home("doc"), "manual"), pattern = "^R-.*html$")
#> [1] "R-admin.html" "R-data.html"  "R-exts.html"  "R-FAQ.html"   "R-intro.html"
#> [6] "R-ints.html"  "R-lang.html"

# How to cite R, and which R this is.
citation()
#> To cite R in publications use:
#>
#>   R Core Team (2026). _R: A Language and Environment for Statistical
#>   Computing_. R Foundation for Statistical Computing, Vienna, Austria.
#>   doi:10.32614/R.manuals <https://doi.org/10.32614/R.manuals>.
#>   <https://www.R-project.org/>.
#>
#> A BibTeX entry for LaTeX users is
#>
#>   @Manual{,
#>     title = {R: A Language and Environment for Statistical Computing},
#>     author = {{R Core Team}},
#>     organization = {R Foundation for Statistical Computing},
#>     address = {Vienna, Austria},
#>     year = {2026},
#>     doi = {10.32614/R.manuals},
#>     url = {https://www.R-project.org/},
#>   }
#>
#> We have invested a lot of time and effort in creating R, please cite it
#> when using it for data analysis. See also ‘citation("pkgname")’ for
#> citing R packages.
R.version.string
#> [1] "R version 4.6.1 (2026-06-24)"
getRversion() >= "4.6.0"
#> [1] TRUE

# NEWS since 4.0.0 is a data frame of class news_db; query it with an
# expression over its columns.
db <- news(Version >= "4.6.0", package = "R")
names(db)
#> [1] "Version"  "Date"     "Category" "Text"     "HTML"
unique(db$Version)
#> [1] "4.6.1" "4.6.0"
unique(db$Category)[1:3]
#> [1] "New Features"                     "Bug Fixes"
#> [3] "Significant User-Visible Changes"
hit <- db[grepl("%notin%", db$Text, fixed = TRUE), ]
hit$Version
#> [1] "4.6.0"
hit$Category
#> [1] "New Features"
substr(gsub("\\s+", " ", hit$Text[[1L]]), 1L, 70L)
#> [1] "x %notin% table newly in base is an idiom for !(x %in% table) and prov"

# sessionInfo() for a bug report: print it without the locale and drop the
# lines that name the platform, the operating system and the linear algebra
# libraries (they differ on every machine).
info <- capture.output(print(sessionInfo(), locale = FALSE))
drop <- grepl("^(Platform|Running|Matrix|BLAS|LAPACK)", info) | !nzchar(info)
cat(info[!drop], sep = "\n")
#> R version 4.6.1 (2026-06-24)
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base
#> loaded via a namespace (and not attached):
#> [1] compiler_4.6.1 tools_4.6.1

books <- read.csv("books.csv")

# The question: why does mean() return NA for the page counts?
mean(books$pages)
#> [1] NA

# Shrink the problem to the columns and rows that show it, and print the
# result with dput() so that others can paste it into their own session.
small <- books[c(5L, 6L, 7L), c("title", "pages")]
dput(small)
#> structure(list(title = c("Midnight Ledger", "A Map of Salt",
#> "Garden of Small Fires"), pages = c(301L, NA, 96L)), row.names = 5:7, class = "data.frame")

# Pasting that into a fresh session rebuilds the same data frame.
small_again <- structure(
  list(
    title = c("Midnight Ledger", "A Map of Salt", "Garden of Small Fires"),
    pages = c(301L, NA, 96L)
  ),
  row.names = 5:7, class = "data.frame"
)
identical(small, small_again)
#> [1] TRUE

# Fix random numbers with set.seed(), so that a sample is the same for all.
set.seed(282)
sample(nrow(books), 3L)
#> [1]  8 13 14

# The minimal example with its answer, and the facts that a report needs.
mean(small$pages, na.rm = TRUE)
#> [1] 198.5
R.version.string
#> [1] "R version 4.6.1 (2026-06-24)"
packageVersion("dplyr")
#> [1] ‘1.2.1’

# Who maintains the code, and where do its bugs go (bug.report() reads this).
maintainer("stats")
#> [1] "R Core Team <do-use-Contact-address@r-project.org>"
packageDescription("dplyr")$BugReports
#> [1] "https://github.com/tidyverse/dplyr/issues"

# reprex is a community package (CRAN); the code below is a fragment.
reprex::reprex({
  x <- c(301L, NA, 96L)
  mean(x)
})

help.request()                       # checklist, then a template post to R-help
bug.report()                         # R itself: opens the bug tracker
bug.report(package = "dplyr")        # a package: its BugReports page or an e-mail

# Each call fails or warns; tryCatch() turns the condition into its text.
text_of <- \(expr) {
  tryCatch(
    {
      expr
      "no condition"
    },
    error = \(e) paste("Error:", conditionMessage(e)),
    warning = \(w) paste("Warning:", conditionMessage(w))
  )
}

# 1. A topic that does not exist is not an error: help() prints two lines.
capture.output(help("foo"))
#> [1] "No documentation for ‘foo’ in specified packages and libraries:"
#> [2] "you could try ‘??foo’"

# 2. example() warns about a missing topic; a missing package is an error.
writeLines(text_of(example(foo)))
#> Warning: no help found for ‘foo’
writeLines(text_of(example("lm", package = "nopkg")))
#> Error: there is no package called ‘nopkg’

# 3. A space in the name makes the question a syntax error (parse() shows
# what the console reports as: Error: unexpected symbol in "?my data").
writeLines(text_of(parse(text = "?my data")))
#> Error: <text>:1:5: unexpected symbol
#> 1: ?my data
#>         ^

# 4. vignette(), demo(), RShowDoc() and help(package =) fail in their own way.
writeLines(text_of(vignette("nonexistent")))
#> Warning: vignette ‘nonexistent’ not found
writeLines(text_of(demo("nodemo")))
#> Error: No demo found for topic ‘nodemo’
writeLines(text_of(RShowDoc("nodoc")))
#> Error: document not found
writeLines(text_of(help(package = "nopkg")))
#> Error: there is no package called ‘nopkg’

# 5. apropos() takes a regular expression, so a bare bracket is invalid.
writeLines(text_of(apropos("[")))
#> Warning: TRE pattern compilation error 'Missing ']''
tryCatch(suppressWarnings(apropos("[")), error = \(e) conditionMessage(e))
#> [1] "invalid regular expression '[', reason 'Missing ']''"
apropos("\\[\\[", mode = "function") |> head(3L)
#> [1] "[["            "[[.data.frame" "[[.Date"