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

\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

\docType

\name

sections, and missing or duplicate

\name

\title

sections).

Author(s)

Duncan Murdoch, Brian Ripley