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 Rd object to use as input.
defines	string(s) to use in ⁠#ifdef⁠ tests.
stages	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).

Author(s)

Duncan Murdoch, Brian Ripley

See Also

parse_Rd, Rd2HTML.

---