| 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 #ifdeftests. |
stages |
at which stage ( \Sexprmacros be executed? See the notes below. |
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
#ifdefand
\Sexprprocessing, 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 | \tabularformat must be simple text |
| 7 | Unrecognized \tabularformat: ... |
| 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 | \docTypemust be plain text |
| 5 | Tag \methodis only valid in \usage |
| 5 | Tag \dontrunis only valid in \examples |
| 5 | Tag tag name is invalid in a block name block |
| 5 | Title of \sectionmust be non-empty plain text |
| 5 | \titlecontent 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 \ldotsis 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 | \methodnot valid outside a code block |
and variations with
\methodreplaced by
\S3methodor
\S4method. 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
\Rdversiondeclarations, invalid
\encodingor
\docTypeor
\namesections, and missing or duplicate
\nameor
\titlesections).
Duncan Murdoch, Brian Ripley