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 3.1.2 Index]