| checkRd {tools} | R Documentation |
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)
Rd |
a filename or |
defines |
string(s) to use in |
stages |
at which stage ( |
unknownOK |
unrecognized macros are treated as errors if
|
listOK |
unnecessary non-empty braces (e.g., around text, not as
an argument) are treated as errors if |
... |
additional parameters to pass to |
def_enc |
logical: has the package declared an encoding, so tests for non-ASCII text are suppressed? |
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 | \docType must be plain text |
| 7 | Tag tag name is invalid in a block name block |
| 7 | \method not valid outside a code block |
| 7 | Tag \method is only valid in \usage |
| 7 | Tag \dontrun is only valid in \examples |
| 7 | Invalid email address: ... |
| 7 | Invalid URL: ... |
| 5 | Must have a tag name |
| 5 | Only one tag name is allowed |
| 5 | Tag tag name must not be empty |
| 5 | Multiple sections named tag name are not allowed |
| 5 | \item in block name must have non-empty label |
| 3 | Empty section tag name |
| -1 | Non-ASCII contents without declared encoding |
| -1 | Non-ASCII contents in second part of \enc |
| -1 | Escaped LaTeX specials: ... |
| -3 | Tag \ldots is invalid 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 ... |
and variations with \method replaced by \S3method or
\S4method, and \dontrun replaced by \donttest or
\dontshow.
Note that both prepare_Rd and checkRd have tests for an
empty section: that in checkRd is stricter (essentially that
nothing is output).
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).
Duncan Murdoch, Brian Ripley