EVOLUTION-MANAGER
Edit File: checkRd.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Check an Rd Object</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for checkRd {tools}"><tr><td>checkRd {tools}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> Check an Rd Object </h2> <h3>Description</h3> <p>Check an help file or the output of the <code><a href="parse_Rd.html">parse_Rd</a></code> function. </p> <h3>Usage</h3> <pre> checkRd(Rd, defines = .Platform$OS.type, stages = "render", unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>Rd</code></td> <td> <p> a filename or <code>Rd</code> object to use as input. </p> </td></tr> <tr valign="top"><td><code>defines</code></td> <td> <p> string(s) to use in <code style="white-space: pre;">#ifdef</code> tests. </p> </td></tr> <tr valign="top"><td><code>stages</code></td> <td> <p> at which stage (<code>"build"</code>, <code>"install"</code>, or <code>"render"</code>) should <code style="white-space: pre;">\Sexpr</code> macros be executed? See the notes below.</p> </td></tr> <tr valign="top"><td><code>unknownOK</code></td> <td> <p> unrecognized macros are treated as errors if <code>FALSE</code>, otherwise warnings. </p> </td></tr> <tr valign="top"><td><code>listOK</code></td> <td> <p> unnecessary non-empty braces (e.g., around text, not as an argument) are treated as errors if <code>FALSE</code>, otherwise warnings.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p> additional parameters to pass to <code><a href="parse_Rd.html">parse_Rd</a></code> when <code>Rd</code> is a filename. One that is often useful is <code>encoding</code>.</p> </td></tr> <tr valign="top"><td><code>def_enc</code></td> <td> <p>logical: has the package declared an encoding, so tests for non-ASCII text are suppressed?</p> </td></tr> </table> <h3>Details</h3> <p><code>checkRd</code> performs consistency checks on an Rd file, confirming that required sections are present, etc. </p> <p>It accepts a filename for an Rd file, and will use <code><a href="parse_Rd.html">parse_Rd</a></code> to parse it before applying the checks. If so, warnings from <code>parse_Rd</code> are collected, together with those from the internal function <code>prepare_Rd</code>, which does the <code style="white-space: pre;">#ifdef</code> and <code style="white-space: pre;">\Sexpr</code> processing, drops sections that would not be rendered or are duplicated (and should not be) and removes empty sections. </p> <p>An Rd object is passed through <code>prepare_Rd</code>, but it may already have been (and installed Rd objects have). </p> <p>Warnings are given a ‘level’: those from <code>prepare_Rd</code> have level 0. These include </p> <table summary="Rd table"> <tr> <td style="text-align: left;"> All text must be in a section</td> </tr> <tr> <td style="text-align: left;"> Only one <var>tag name</var> section is allowed: the first will be used</td> </tr> <tr> <td style="text-align: left;"> Section <var>name</var> is unrecognized and will be dropped</td> </tr> <tr> <td style="text-align: left;"> Dropping empty section <var>name</var></td> </tr> <tr> <td style="text-align: left;"> </td> </tr> </table> <p><code>checkRd</code> itself can show </p> <table summary="Rd table"> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Tag <var>tag name</var> not recognized</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> <code style="white-space: pre;">\tabular</code> format must be simple text</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Unrecognized <code style="white-space: pre;">\tabular</code> format: ...</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Only <var>n</var> columns allowed in this table</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Must have a <var>tag name</var></td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Only one <var>tag name</var> is allowed</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> Tag <var>tag name</var> must not be empty</td> </tr> <tr> <td style="text-align: right;"> 7 </td><td style="text-align: left;"> <code style="white-space: pre;">\docType</code> must be plain text</td> </tr> <tr> <td style="text-align: right;"> 5 </td><td style="text-align: left;"> Tag <code style="white-space: pre;">\method</code> is only valid in <code style="white-space: pre;">\usage</code></td> </tr> <tr> <td style="text-align: right;"> 5 </td><td style="text-align: left;"> Tag <code style="white-space: pre;">\dontrun</code> is only valid in <code style="white-space: pre;">\examples</code></td> </tr> <tr> <td style="text-align: right;"> 5 </td><td style="text-align: left;"> Tag <var>tag name</var> is invalid in a <var>block name</var> block</td> </tr> <tr> <td style="text-align: right;"> 5 </td><td style="text-align: left;"> Title of <code style="white-space: pre;">\section</code> must be non-empty plain text</td> </tr> <tr> <td style="text-align: right;"> 5 </td><td style="text-align: left;"> <code style="white-space: pre;">\title</code> content must be plain text</td> </tr> <tr> <td style="text-align: right;"> 3 </td><td style="text-align: left;"> Empty section <var>tag name</var></td> </tr> <tr> <td style="text-align: right;"> -1 </td><td style="text-align: left;"> Non-ASCII contents without declared encoding</td> </tr> <tr> <td style="text-align: right;"> -1 </td><td style="text-align: left;"> Non-ASCII contents in second part of <code style="white-space: pre;">\enc</code></td> </tr> <tr> <td style="text-align: right;"> -3 </td><td style="text-align: left;"> Tag <code style="white-space: pre;">\ldots</code> is not valid in a code block</td> </tr> <tr> <td style="text-align: right;"> -3 </td><td style="text-align: left;"> Apparent non-ASCII contents without declared encoding</td> </tr> <tr> <td style="text-align: right;"> -3 </td><td style="text-align: left;"> Apparent non-ASCII contents in second part of <code style="white-space: pre;">\enc</code></td> </tr> <tr> <td style="text-align: right;"> -3 </td><td style="text-align: left;"> Unnecessary braces at ...</td> </tr> <tr> <td style="text-align: right;"> -3 </td><td style="text-align: left;"> <code style="white-space: pre;">\method</code> not valid outside a code block</td> </tr> <tr> <td style="text-align: right;"> </td> </tr> </table> <p>and variations with <code style="white-space: pre;">\method</code> replaced by <code style="white-space: pre;">\S3method</code> or <code style="white-space: pre;">\S4method</code>. </p> <p>Note that both <code>prepare_Rd</code> and <code>checkRd</code> have tests for an empty section: that in <code>checkRd</code> is stricter (essentially that nothing is output). </p> <h3>Value</h3> <p>This may fail through an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> error, but otherwise warnings are collected as returned as an object of class <code>"checkRd"</code>, a character vector of messages. This class has a <code>print</code> method which only prints unique messages, and has argument <code>minlevel</code> that can be used to select only more serious messages. (This is set to <code>-1</code> in <code>R CMD check</code>.) </p> <p>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 <code>prepare_Rd</code> (multiple <code style="white-space: pre;">\Rdversion</code> declarations, invalid <code style="white-space: pre;">\encoding</code> or <code style="white-space: pre;">\docType</code> or <code style="white-space: pre;">\name</code> sections, and missing or duplicate <code style="white-space: pre;">\name</code> or <code style="white-space: pre;">\title</code> sections). </p> <h3>Author(s)</h3> <p>Duncan Murdoch, Brian Ripley </p> <h3>See Also</h3> <p><code><a href="parse_Rd.html">parse_Rd</a></code>, <code><a href="Rd2HTML.html">Rd2HTML</a></code>. </p> <hr /><div style="text-align: center;">[Package <em>tools</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>