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 (“Lost braces”).

...

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

⁠\Sexpr⁠ expects R code; found ...
Unprocessed ‘stage’ macro from stage-stage ⁠\Sexpr⁠
All text must be in a section
Only one tag name section is allowed: the first will be used
docType type is unrecognized
Section name is unrecognized and will be dropped
Dropping empty section name

checkRd itself can show

7 Tag tag name not recognized
7 Unrecognized format: ...
7 ⁠\tabular⁠ format must be simple text
7 Unrecognized ⁠\tabular⁠ format: ...
7 Only n columns allowed in this table
7 Tag tag name is invalid in a block name block
7 ⁠\method⁠ not valid outside a code block
7 Tag ⁠\method⁠ is only valid in ⁠\usage⁠
7 Tag ⁠\dontrun⁠ is only valid in ⁠\examples⁠
7 Invalid email address: ...
7 Invalid URL: ...
5 ⁠\name⁠ should not contain !, | or @
5 ⁠\item⁠ in block name must have non-empty label
3 Empty section tag name
-1 ⁠\name⁠ should only contain printable ASCII characters
-1 Non-ASCII contents without declared encoding
-1 Non-ASCII contents in second part of ⁠\enc⁠
-1 Escaped LaTeX specials: ...
-1|-3 Lost braces ...
-3 Tag ⁠\ldots⁠ is invalid in a code block
-5 ⁠\title⁠ should not end in a period

and variations with ⁠\method⁠ replaced by ⁠\S3method⁠ or ⁠\S4method⁠, ⁠\dontrun⁠ replaced by ⁠\donttest⁠, ⁠\dontdiff⁠ or ⁠\dontshow⁠, and ⁠\title⁠ replaced by ⁠\section⁠ or ⁠\subsection⁠ name. “Lost braces” are uprated to warning level -1 when they match common markup mistakes, e.g., ‘⁠code{text}⁠’ rendered as ‘⁠codetext⁠’ due to the missing backslash escape for the macro name.

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 !unknownOK or !listOK, from invalid ⁠\if⁠ or ⁠\ifelse⁠ conditions, from running the parser (e.g., a non-existent file, unclosed quoted string, non-ASCII input without a specified encoding, an invalid value for an ⁠\Sexpr⁠ option), or from prepare_Rd (multiple ⁠\Rdversion⁠ declarations, invalid ⁠\encoding⁠ or ⁠\docType⁠ or ⁠\name⁠ sections, and missing or duplicate ⁠\name⁠ or ⁠\title⁠ sections), including errors from parsing/running code from ⁠\Sexpr⁠ macros (if covered by stages).

Author(s)

Duncan Murdoch, Brian Ripley

See Also

parse_Rd, Rd2HTML.

Examples

## parsed Rd from the installed version of _this_ help file
rd <- Rd_db("tools")[["checkRd.Rd"]]
rd
stopifnot(length(checkRd(rd)) == 0)  # there should be no issues

## make up \tabular issues
bad <- r"(\name{bad}\title{bad}\description{\tabular{p}{1 \tab 2}})"
(res <- checkRd(parse_Rd(textConnection(bad))))
stopifnot(length(res) > 0)

[Package tools version 4.4.1 Index]