| checkRd {tools} | R Documentation |
Check an Rd Object
Description
Check an help file or the output of the parse_Rd function.
Usage
checkRd(Rd, defines = .Platform$OS.type, stages = "render",
unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE)
Arguments
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? |
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
\Sexpr expects R code; found ... |
Unprocessed ‘stage’ macro from stage-stage \Sexpr |
| All text must be in a section |
| Only one tag name section is allowed: the first will be used |
| docType type is unrecognized |
| Section name is unrecognized and will be dropped |
| Dropping empty section name |
checkRd itself can show
| 7 | Tag tag name not recognized |
| 7 | Unrecognized format: ... |
| 7 | \tabular format must be simple text |
| 7 | Unrecognized \tabular format: ... |
| 7 | Only n columns allowed in this table |
| 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 | \name should not contain !, | or @ |
| 5 | \item in block name must have non-empty label |
| 3 | Empty section tag name |
| -1 | \name should only contain printable ASCII characters |
| -1 | Non-ASCII contents without declared encoding |
| -1 | Non-ASCII contents in second part of \enc |
| -1 | Escaped LaTeX specials: ... |
| -1|-3 | Lost braces ... |
| -3 | Tag \ldots is invalid in a code block |
| -5 | \title should not end in a period |
and variations with \method replaced by \S3method or
\S4method, \dontrun replaced by \donttest, \dontdiff or
\dontshow, and \title replaced by \section or
\subsection name.
“Lost braces” are uprated to warning level -1 when they match
common markup mistakes, e.g., ‘code{text}’ rendered as
‘codetext’ due to the missing backslash escape for the macro name.
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 !unknownOK or !listOK,
from invalid \if or \ifelse conditions,
from running the parser (e.g., a
non-existent file, unclosed quoted string, non-ASCII input without a
specified encoding, an invalid value for an \Sexpr option),
or from prepare_Rd (multiple
\Rdversion declarations, invalid \encoding or
\docType or \name sections, and missing or duplicate
\name or \title sections),
including errors from parsing/running code from \Sexpr macros
(if covered by stages).
Author(s)
Duncan Murdoch, Brian Ripley
See Also
Examples
## parsed Rd from the installed version of _this_ help file
rd <- Rd_db("tools")[["checkRd.Rd"]]
rd
stopifnot(length(checkRd(rd)) == 0) # there should be no issues
## make up \tabular issues
bad <- r"(\name{bad}\title{bad}\description{\tabular{p}{1 \tab 2}})"
(res <- checkRd(parse_Rd(textConnection(bad))))
stopifnot(length(res) > 0)