R: Check an Rd Object

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