at which stage ("build", "install", or
"render") should Sexpr macros be executed? See the
notes below.
unknownOK
unrecognized macros are treated as errors if
FALSE, otherwise warnings.
listOK
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.
def_enc
logical: has the package declared an encoding, so tests
for non-ASCII text are suppressed?
Details
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).
Value
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).