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

### See Also

`parse_Rd`, `Rd2HTML`.

[Package tools version 4.0.5 Index]