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