Check an help file or the output of the parse_Rd function.
checkRd(Rd, defines = .Platform$OS.type, stages = "render",
unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE)a filename or Rd object to use as input.
string(s) to use in #ifdef tests.
at which stage ("build", "install", or
"render") should \Sexpr macros be executed? See the
notes below.
unrecognized macros are treated as errors if
FALSE, otherwise warnings.
unnecessary non-empty braces (e.g., around text, not as
an argument) are treated as errors if FALSE, otherwise
warnings.
additional parameters to pass to parse_Rd when
Rd is a filename. One that is often useful is encoding.
logical: has the package declared an encoding, so tests for non-ASCII text are suppressed?
This may fail through an R error, but otherwise warnings are
collected as returned as an object of class "checkRd", a
character vector of messages. This class has a print method
which only prints unique messages, and has argument minlevel
that can be used to select only more serious messages. (This is set
to -1 in R CMD check.)
Possible fatal errors are those from running the parser (e.g., a
non-existent file, unclosed quoted string, non-ASCII input without a
specified encoding) or from prepare_Rd (multiple
\Rdversion declarations, invalid \encoding or
\docType or \name sections, and missing or duplicate
\name or \title sections).
checkRd performs consistency checks on an Rd file, confirming that
required sections are present, etc.
It accepts a filename for an Rd file, and will use
parse_Rd to parse it before applying the checks. If so,
warnings from parse_Rd are collected, together with those from
the internal function prepare_Rd, which does the
#ifdef and \Sexpr processing, drops sections that
would not be rendered or are duplicated (and should not be) and
removes empty sections.
An Rd object is passed through prepare_Rd, but it may already
have been (and installed Rd objects have).
Warnings are given a ‘level’: those from prepare_Rd have
level 0. These include
| All text must be in a section |
| Only one tag name section is allowed: the first will be used |
| Section name is unrecognized and will be dropped |
| Dropping empty section name |
checkRd itself can show
| 7 | Tag tag name not recognized |
| 7 | \tabular format must be simple text |
| 7 | Unrecognized \tabular format: … |
| 7 | Only n columns allowed in this table |
| 7 | Must have a tag name |
| 7 | Only one tag name is allowed |
| 7 | Tag tag name must not be empty |
| 7 | \docType must be plain text |
| 5 | Tag \method is only valid in \usage |
| 5 | Tag \dontrun is only valid in \examples |
| 5 | Tag tag name is invalid in a block name block |
| 5 | Title of \section must be non-empty plain text |
| 5 | \title content must be plain text |
| 3 | Empty section tag name |
| -1 | Non-ASCII contents without declared encoding |
| -1 | Non-ASCII contents in second part of \enc |
| -3 | Tag \ldots is not valid in a code block |
| -3 | Apparent non-ASCII contents without declared encoding |
| -3 | Apparent non-ASCII contents in second part of \enc |
| -3 | Unnecessary braces at … |
| -3 | \method not valid outside a code block |
and variations with \method replaced by \S3method or
\S4method.
Note that both prepare_Rd and checkRd have tests for an
empty section: that in checkRd is stricter (essentially that
nothing is output).